New Proposal Calls for Contributors to Stop Merging Experimental APIs from Gutenberg to WordPress Core

The practice of merging experimental APIs from Gutenberg into WordPress core may soon be coming to an end. A new proposal, published by Automattic-sponsored contributor Adam Zielinski, calls for contributors to stabilize APIs before merging them into core.

Over the years, approximately 280 experimental APIs have been merged from the Gutenberg plugin, which Zielinski audited in a ticket he opened for the issue in April. In balancing the drive to move fast with iterating on the editor(s) against WordPress’ commitment to backwards compatibility, the number of experimental APIs has become untenable and the practice of merging them into core is now being actively reconsidered.

Officially, the experimental APIs are flagged as such to discourage third-party use, since they are expected to change. In practice, people building for the block editor are using them anyway because they are in core and they want to extend the features these APIs enable.

“Plugin and theme authors are forced to rely on the __experimental  features that could get removed or changed in a backwards incompatible way at any time,” Zielinski said, echoing the frustration and concerns many developers have had with the project the past few years. “It is a serious maintenance burden. Every new Gutenberg/WordPress release means potentially breaking changes.”

WordPress core committer Peter Wilson commented on the ticket, saying he is in favor of limiting experimental APIs to bleeding edge product. Driving home the need for this change, he cited a host of negative impacts that these core experimental APIs have had on the ecosystem:

• core committers unwilling to use certain library features to make core tasks easier because they don’t trust the reliability
• developers no longer upgrading WP client sites. As a core committer who has strived to maintain backward compatibility for years this disappoints me. As a security team member it’s greatly concerning
• developers deciding to include copies of packages in themes and plugins rather than rely on the wp.* globals. Again this concerns me from a security perspective but it also increases the JavaScript payload significantly more than maintaining backward compatibility
• reports of backward compatibility breaks in minor versions: “you don’t expect a 5.9.1 release to break the responsiveness of a bunch of images in our sites outside the block editor”
• developers considering never using core blocks because they’re too unstable: “I stopped using/extending core blocks because they were changing too much and I’ve been using ACF Blocks so that I at least I know I can make blocks that won’t break. Granted the UI isn’t as good as core blocks but I’ll take stability over blocks breaking any time.”

The Gutenberg plugin was meant to function as a feature plugin where breaks in backwards compatibility are expected while contributors polish features before merging them into core. Getting back to the roots of this approach, and making the editor less experimental, is at center of this proposal.

“Instability between versions is already beginning to alienate some of the block-editors biggest external advocates,” Wilson said.

Maintaining this level of instability could discourage people from building on WordPress, pushing them away to other more straightforward projects that are managed in a different way. It is possible that the need to rely on experimental APIs has discouraged developers from building more products, slowing block editor adoption.

“As a plugin author that is currently using many __experimental APIs, I would love to see these stabilized,” WP Engine-sponsored contributors Nick Diego said. “Most provide crucial functionality but building a product that relies on an __experimental API is always a bit disconcerting. So long as the process is exceedingly transparent, is well publicized, and we provide plugin/theme authors with a guide on how to migrate to stable versions, then I like this initiative.”

After months of discussion on the ticket, Zielinski distilled contributors’ concerns into the plan of action proposed on the Make WordPress Core blog.

The proposal indicates that most of the existing experimental APIs already merged into core would get a stable alias.

“It would preserve backwards compatibility and shouldn’t noticeably affect the bundle size,” Zielinski said. “Some will need a different treatment; let’s discuss that case-by-case.” He also recommended contributors consider whether an existing experimental API already in core needs to be removed. He doesn’t anticipate many instances of this but recommends these use established practices of contacting plugin authors, using soft deprecations, and publishing Core posts.

“I also see two things at play here: the use and abuse of experimental APIs during the API design (generally to be used and tested in the Gutenberg plugin) and the lack of a diligent process for stabilizing them when they satisfy design criteria,” Gutenberg lead architect Matias Ventura commented on the original ticket. “The ones that are to be considered de facto public are those that have existed for many releases in a stable form despite their nomenclature.”

In the interest of preserving WordPress’ ability to deliver on its backwards compatibility promises, the proposal recommends experimental APIs be restricted to the Gutenberg plugin and never merged into core. In the instances where a stable feature depends on an experimental API, Zielinski identified a simple answer:

“Then it isn’t actually stable. Let’s stabilize the dependencies first.”

This is essentially a new way of moving forward that should increase stability and confidence in WordPress’ APIs and updates, but it does have a few drawbacks.

Users and contributors can expect that Gutenberg features may be slower merging into core, as they cannot rely on experimental APIs when they hit prime time distribution in major releases. Zielinski also noted that contributors may also have difficulty refactoring these APIs once they have shipped and go into use on millions of WordPress sites.

So far the proposal has had overwhelmingly positive support, as many believe these APIs should never have arrived to core in the first place while still in the experimental stage.

“I’m very much in favor of this approach,” WordPress developer Mark Root-Wiley said. “I build custom themes and have a few simple plugins. For both, I have found myself somewhat frequently forced to deal with experimental APIs and the difficulties of keeping up to date with them when features are put in core that can only be turned off, adjusted, or extended through an experimental API.”

“A return to this sort of stability in core would go a long way to regaining some developer goodwill,” WordPress contributor Dovid Levine commented on the proposal.

The deadline for commenting on the proposal is September 7, which would close out the discussion just shy of three weeks before WordPress 6.1 Beta 1 is expected. This gives contributors some time to more deeply audit the experimental APIs ahead of the next major release, should they reach a consensus on restricting them to the Gutenberg plugin.