Recent Proposal Calls for Contributors to Stop Merging Experimental APIs from Gutenberg to WordPress Core – WP Tavern

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

Over time, roughly 280 experimental APIs have been merged from the Gutenberg plugin, which Zielinski audited in a ticket he opened for the problem in April. In balancing the drive to maneuver fast with iterating on the editor(s) against WordPress’ commitment to backwards compatibility, the variety of experimental APIs has grow to be 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’re expected to vary. In practice, people constructing for the block editor are using them anyway because they’re in core and so they wish 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’s in favor of limiting experimental APIs to bleeding edge product. Driving home the necessity for this modification, he cited a bunch of negative impacts that these core experimental APIs have had on the ecosystem:

  • core committers unwilling to make use of certain library features to make core tasks easier because they don’t trust the reliability
  • developers not upgrading WP client sites. As a core committer who has strived to take care of backward compatibility for years this disappoints me. As a security team member it’s greatly concerning
  • developers deciding to incorporate copies of packages in themes and plugins relatively than depend on the wp.* globals. Again this concerns me from a security perspective however it also increases the JavaScript payload significantly greater 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 operate 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 constructing on WordPress, pushing them away to other more straightforward projects which are managed otherwise. It is feasible that the necessity to depend on experimental APIs has discouraged developers from constructing 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 debate on the ticket, Zielinski distilled contributors’ concerns into the plan of motion proposed on the Make WordPress Core blog.

The proposal indicates that the majority of the prevailing 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 really useful contributors consider whether an existing experimental API already in core must 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 unique 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.”

Within the interest of preserving WordPress’ ability to deliver on its backwards compatibility guarantees, the proposal recommends experimental APIs be restricted to the Gutenberg plugin and never merged into core. Within the instances where a stable feature is dependent upon an experimental API, Zielinski identified an easy answer:

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

This is basically a latest way of moving forward that ought to increase stability and confidence in WordPress’ APIs and updates, however it does have a number of drawbacks.

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

Thus far the proposal has had overwhelmingly positive support, as many consider these APIs should never have arrived to core in the primary place while still within 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 might close out the discussion just shy of three weeks before WordPress 6.1 Beta 1 is anticipated. This offers contributors a while to more deeply audit the experimental APIs ahead of the subsequent major release, should they reach a consensus on restricting them to the Gutenberg plugin.

Leave a Reply

Your email address will not be published. Required fields are marked *