New Proposal Asks Contributors to Stop Merging Experimental Gutenberg APIs to WordPress Core


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

Over the years, around 280 experimental APIs have been merged from the Gutenberg plugin, which Zielinski audited in a ticket he opened for the issue in April. Balancing the desire to go fast with iteration 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 the core is now actively reconsidered.

Officially, experimental APIs are marked as such to discourage third-party use, as they are subject to change. In practice, people who build for the block editor use them anyway because they are in the core and want to extend the functionality enabled by these APIs.

“Plugin and theme authors are forced to rely on the __experimental features that could be removed or changed backwards compatible at any time,” Zielinski said, echoing the frustration and concerns many developers have had with the project in recent years. “It’s a heavy maintenance burden. Each new version of Gutenberg/WordPress involves potentially significant changes. »

Senior WordPress maintainer Peter Wilson commented on the ticket, saying he was in favor of limiting experimental APIs to cutting-edge products. Highlighting the need for this change, he cited a host of negative impacts that these basic experimental APIs have had on the ecosystem:

  • core committers don’t want to use some library features to make core tasks easier because they don’t trust reliability
  • developers no longer update WP client sites. As a core committer who has struggled to maintain backwards compatibility for years, this disappoints me. As a member of the security team, it is of great concern
  • developers deciding to include copies of packages in themes and plugins rather than relying on the wp.* global. Again, this concerns me from a security perspective, but it also increases the JavaScript payload much more than maintaining backwards compatibility
  • reports of backward compatibility breaks in minor releases: “you wouldn’t expect a 5.9.1 release to break the responsiveness of a bunch of images on our sites outside of the block editor”
  • developers consider never using base blocks because they are too unstable: “I stopped using/extending base blocks because they changed too much and used ACF blocks for that at least I know I can create blocks that won’t Break. Granted the UI isn’t as good as the basic blocks, but I’ll take some stability on the blocks that break at any time.

The Gutenberg plugin was meant to work as a feature plugin where backward compatibility breaks are expected while contributors tweak features before merging them into the core. Going back to the roots of this approach, and making the editor less experimental, is at the heart of this proposal.

“The instability between releases 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, simpler projects that are handled in a different way. It’s possible that the need to rely on experimental APIs has discouraged developers from building more products, thus slowing the adoption of the block editor.

“As a plugin author currently using many __experimental APIs, would love to see them stabilized,” said WP Engine sponsored contributor Nick Diego. “Most provide crucial functionality, but building a product that relies on a __experimental The API is still a bit confusing. As long as the process is extremely transparent, well publicized, and we provide plugin/theme authors with a guide on how to migrate to stable releases, then I like this initiative.

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

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

“This would preserve backwards compatibility and shouldn’t significantly affect bundle size,” Zielinski said. “Some will need different treatment; let’s discuss it on a case-by-case basis. He also recommended that contributors consider whether an existing experimental API already in the kernel should be removed. He doesn’t anticipate many such cases, but recommends that they use established practices of contacting plugin authors, using soft deprecations, and posting to Core.

“I also see two things at play here: the use and abuse of experimental APIs when designing the API (usually to be used and tested in the Gutenberg plugin) and the lack of a diligent process to stabilize them when they meet design criteria,” Gutenberg’s lead architect, Matias Ventura, commented on the original post. “Those who must be considered de facto public are those that have existed for many versions in a stable form despite their nomenclature.

In the interest of preserving WordPress’ ability to deliver on its backward compatibility promises, the proposal recommends that experimental APIs be limited to the Gutenberg plugin and never merged with the core. In cases where stable functionality depends on an experimental API, Zielinski identified a simple answer:

“So it’s not really stable. Let’s stabilize the dependencies first.

This is essentially a new way forward that should increase stability and trust in WordPress APIs and updates, but it has a few downsides.

Users and contributors can expect Gutenberg features to be slower to merge with the core because they can’t rely on experimental APIs when distributed at prime time in releases. majors. Zielinski also noted that contributors may also have difficulty refactoring these APIs once they’ve been shipped and live on millions of WordPress sites.

So far, the proposal has received overwhelmingly positive support, as many believe that these APIs should never have made it to the core in the first place when they were still in the experimental stage.

“I’m very supportive of this approach,” said WordPress developer Mark Root-Wiley. “I create custom themes and have a few simple plugins. For both, I quite frequently found myself having to deal with experimental APIs and the difficulties of keeping up to date with them when features are introduced that cannot be disabled, adjusted or extended only via an experimental API.

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

The deadline for commenting on the proposal is September 7, which would close the discussion just under three weeks before WordPress 6.1 Beta 1 is due. This gives contributors some time to further audit the experimental APIs before the next major release, if they reach consensus on their restriction to the Gutenberg plugin.

Add Comment