The problem

The new lock()/unlock() API doesn't allow exporting experimental APIs from the Gutenebrg plugin. It only enables sharing private APIs between Gutenberg packages.

Shipping public experimental APIs in the Gutenberg plugin enables developer to test them and provide feedback. This informs and shapes the Gutenberg plugin development. Historically, Gutenberg exported experimental APIs with the __experimental prefix. An unfortunate consequence was that they often got merged to WordPress core where they became stable APIs.

Proposed solution

I propose to:

• Rename the @wordpress/experiments package to @wordpress/private-apis to clearly communicate its purpose
• Only use the lock()/unlock() utilities to make APIs private and inaccessible in WordPress Core
• Manually export experimental APIs from the Gutenberg plugin without merging them in WordPress Core

In practice, it would look like this:

// This function can't be used by extenders in any context:
function privateApi() {}

// This function can be used by extenders with the Gutenberg plugin but not in vanilla WordPress Core:
function experimentalApi() {}

// Gutenberg treats both functions as private APIs internally:
const experiments = {};
lock(experiments, { privateApi, experimentalApi });

// The experimental API is explicitly exported. Using IS_GUTENBERG_PLUGIN 
// allows Webpack to exclude the experimental export from WordPress core. 
if ( IS_GUTENBERG_PLUGIN ) {
   export function __experimentalApi() {
       return unlock( experiments ).experimentalApi( ...arguments );
   }
}

cc @youknowriad @talldan @gziolo @luisherranz @dmsnell @jsnajdr @mcsf @peterwilsoncc