Proposal: Stop merging experimental APIs from Gutenberg to WordPress Core

This call for feedback will be open for the next four weeks until September 7th.

I propose a way of harmonizing the process of merging new APIs from the GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party to the WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.. Right now, the two projects have very different policies, confusing contributors and sparking lively discussions on every major WordPress release. 

Today, experimental APIs are merged to Core and sometimes removed later

To date, 280 experimental APIs were merged from the Gutenberg plugin to WordPress Core. That’s problematic, and here’s why.

WordPress values backward compatibility. Upgrading to a new version should not break the plugins and themes, so WordPress public APIs these plugins and themes depend on are maintained across major versions. As the WordPress handbook states:

Historically, WordPress has been known for preserving backward compatibility across versions. 

The Gutenberg plugin values agility. It’s the safe space where new experiments are planted and grow into stable features without the same stability constraints. It is okay to ship a prototype, learn from it, and then start over again. New functions under active development often include the __experimental prefix in their name to indicate they may change at any point and shouldn’t be relied upon. Removing the obsolete code also makes the JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. bundle smaller and reduces the editor loading time. As the Gutenberg plugin handbook states:

Experimental and unstable APIs are temporary values exported from a module whose existence is either pending future revision or provides an immediate means to an end.

In the Gutenberg plugin, it’s fine to remove these experimental APIs. In WordPress, it’s not. Unfortunately, many have already been released with major WordPress versions.

Tomorrow, experimental APIs could be restricted to the Gutenberg plugin and never merged to Core

Let’s remove the experimental prefix before merging new APIs into WordPress Core.

This way:

• Core can deliver the expected level of Backwards Compatibility
• The Gutenberg plugin can retain the freedom to remove the experimental APIs as needed
• The experimental APIs would get audits
• It would make the release easier

Wouldn’t stabilizing every APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. before the release slow down new features?

The goal isn’t to stabilize. It’s to avoid adding public experimental APIs to WordPress core. Here’s two alternatives to stabilizing:

• Ship a private API instead of a public experimental API. Here’s how, and here’s a proposed system for private cross-package APIs.
• Exclude the in-progress features from production builds using feature flags.

What if a stable feature depends on an experimental feature?

Then it isn’t actually stable. Let’s stabilize the dependencies first (or make them private).

What about the existing experimental APIs?

Most of those already merged to Core would get a stable alias. It would preserve BC and shouldn’t noticeably affect the bundle size. Some will need a different treatment; let’s discuss that case-by-case.

What if an existing experimental API already in Core needs to be removed?

Does it? If so, let’s consider that on a case-by-case basis. There are established Core practices like contacting plugin authors, writing make Core posts, preferring soft deprecations, and so on. I don’t expect to see many instances of this.

What if a future stable Gutenberg plugin API really needs to be removed after it’s released in Core?

Yes, it will happen. Let’s acknowledge and embrace it. Some good reasons were mentioned in the GitHub discussion, and the future will surprise us with many new ones. Again, let’s follow the established Core practices. For example, deprecated.php shows that removing a function body is sometimes okay as long as the name keeps working.

What are the downsides?

I can see three:

• Some Gutenberg plugin features will get merged into the Core later that they currently would be. The total amount of the development work won’t change, but the merging timeline will. That could be a good thing. Using the Gutenberg plugin is the intended way of accessing the upcoming features early.
• Refactoring Gutenberg plugin APIs will be difficult once they get shipped with Core. In reality, that’s already the case.
• Risk: Surgically removing all the Gutenberg plugin work spanning multiple WordPress releases from pre-release merges may become too complex. It would halt the merges entirely. If this risk does materialize, the merge guidelines will need to be adjusted again.

If you see any other downsides, please speak out!

What alternatives have been considered?

• Keep not acting on the problem.
• Use the same Backwards Compatibility policy for both WordPress and the Gutenberg plugin – which would make both projects worse off.
• Find a way to ship the experimental APIs with Core as “internal” and unavailable to plugin authors – which has been explored without a successful resolution.

Unfortunately, neither is viable, as explained in more detail in the GitHub discussion.

If this resonates with you, speak out before September 7th!

Policies don’t contribute to the Gutenberg plugin. People do. This proposal will only work if we, the contributors, believe it’s the right thing to do.

Please share your thoughts under this post or in the GitHub discussion – even if it’s just “I like it.” All opinions are welcome, especially if you are not convinced about this proposal.

This call for feedback will be open until September 7th.

Props to Birgit Pauli-Haack (@bph), Grzegorz Ziółkowski (@gziolo), and Hector Prieto (@priethor) for their help in putting this proposal together.

#editor #gutenberg #core #proposal