Separate Private APIs from Experimental APIs

[adamziel]

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

[youknowriad]

I think we should rename the package indeed, and sooner rather than later (before 6.2)

[peterwilsoncc]

I agree, private-apis is a better name.

For the purposes of WordPress 6.2, would it be possible to limit the addition of IS_GUTENBERG_PLUGIN code to gutenberg trunk for the time being and simply rename the package is the appropriate wp/* branch? That will reduce the chance of unintended side-affects.

[mcsf]

I think the proposal is consistent with the direction we've been taking, including the renaming.

If I have to pick nits from the example, I see APIs are exported by creating a new function for each one:

// 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 );
   }
}

I wonder if this is unnecessary overhead compared to simply exposing exported objects:

if ( IS_GUTENBERG_PLUGIN ) {
   export const __experimentalApi = unlock( experiments ).experimentalApi;
}

[adamziel]

@mcsf I like exporting the objects directly! I’ll prepare a PR and a documentation update.

@peterwilsoncc I’m not aware of any experimental API that’s awaiting urgent release before 6.2 so I think we’re good.

As for renaming the package in a wp/* branch, sure. Just to be sure - I also want to do it in trunk. Or is there a reason not to?

[adamziel]

I started two related PRs:

• [Trunk] Rename experiments package to private-apis #47839
• [WP 6.2] Rename experiments package to private-apis  #47840

I'm still working on getting the CI to pass

[peterwilsoncc]

As for renaming the package in a wp/* branch, sure. Just to be sure - I also want to do it in trunk. Or is there a reason not to?

Not that I can see, no.

My main thought for limiting the changes in the wp/6.2 branch is it's less risky during beta. I'll find time to look at the PRs shortly.

[adamziel]

Here's the documentation update: #47785

[adamziel]

The only remaining part of this issue is the coding guidelines change:

#47973

I'll appreciate your reviews so we can close this.

[adamziel]

Closing this issue since #47937 is now merged. Yay!