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.


8 responses to “New Proposal Calls for Contributors to Stop Merging Experimental APIs from Gutenberg to WordPress Core”

  1. As an end user of the software much of this internal engineering of WordPress should be no concern of mine. To use a Mac comparison, it should just work. The fact that these issues are highlighted explains much of the anxiety that the block editor and the Gutenberg project has brought to the WordPress community. Lately I have seen Toolset announce that they would be pausing much of their development on the Toolset suite due to issues such as this. This is a big no no as years of work look like it could be ripped out if third party plugins are adversely tipped out by the whims of some project methodology that doesn’t secure the work done by others. Bit of a lack of respect there.

  2. ““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.”

    About time someone in core realized this.

  3. Gutenberg continues to add new chapters to its world renowned case study:

    “How not to launch and manage a product”

    It’s as if the Core Bubble has no idea what’s happening in the real world.

    It would be funny if it was so sad and frustrating.

  4. The fact that 280 experimental APIs where merged into core says a lot as to the weighted Gutenberg has compare to every other WP project. I mean, which other WP could get away with merging 2 experimental APIs into core?

  5. I’m not going to say “all of Gutenberg seems experimental,” because blocks are now clearly out of alpha, thanks especially to more capable and experienced 3rd parties like Kadence and Generate, who seem to have a grip on concepts like “responsive page layout,” “usability,” “interface design,” and “performance.”

    Instead I’m going to say that blocks shouldn’t have been added to core at all unless and until we start seeing the original promise that data storage for blocks would be more than glorified comments in the body-field blob. Because even dinosaur page builders like VisualComposer are easier and more flexible blob editors than Gutenberg has been so far.

    And, seriously, who’s bright idea was it to allow by-definition-unstable __experimental code in core in the first place?


Subscribe Via Email

Enter your email address to subscribe to this blog and receive notifications of new posts by email.