Proposal: improve the editor tech workflow for major releases

Following on from this conversation, let’s look at how this process can be run more smoothly!

The Problem

Updating coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. with the latest features 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. 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 Plugin Directory or can be cost-based plugin from a third-party almost always causes problems and delays at release time. Historically, it has been done in a large batch just before BetaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. 1, and the volume of changes means there is a high probability of something going wrong in the process.

A brief look through the “retrospective“ tag shows this has been a major releasemajor release A release, identified by the first two numbers (3.6), which is the focus of a full release cycle and feature development. WordPress uses decimaling count for major release versions, so 2.8, 2.9, 3.0, and 3.1 are sequential and comparable in scope. pain point for a while.

The idea of syncing Gutenberg code to core earlier in the release cycle has often been mentioned as a way to fix or at least ease the pain of this process: by merging new features into core as they are developed, it’s possible to fix any bugs identified during the process as they are caught, the new features get a little extra testing in trunktrunk A directory in Subversion containing the latest development code in preparation for the next major release cycle. If you are running "trunk", then you are on the latest revision., and most importantly, the risk of things going wrong on the eve of major release milestones is substantially reduced, with much less stress for all involved.

So, let’s get doing this! But… why has this idea been recurrently mentioned as a good solution, and still not implemented?

The answer lies mostly in the Gutenberg development process, and its differences from the rest of core.

Iterative code

Developing features in Gutenberg often starts as a quick, messy experimental process, before stabilising into mature, tested, shippable code. And there are multiple features simultaneously in development, which means that at any given point, there is some amount of unstable code in the plugin, which is undesirable to have in core. 

The good news is that there are mechanisms already available to avoid merging unstable code into core: using the IS_GUTENBERG_PLUGIN flag means that code won’t run in core. The historical __unstable and __experimental prefixes previously used in functions are being replaced with a private 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. system that makes experimental code inaccessible to extenders.

These mechanisms are not uniformly enforced during development though, and this is where there is some room for improvement. Whereas it’s possible to measure things like code coverage, there is no good way to automate checking whether code is otherwise stable or not, so implementation is largely up to individual contributors. Here is where documentation of expectations for the development process might be useful, so folks are aware that these rules exist and why.

Package ecosystem problems

Given that core largely consumes Gutenberg code in the shape of npm packages, there are occasional hiccups due to breaking changes in dependencies that are only noticed in core. This is because the package install process pulls the latest versions of all nested dependencies that might have not yet been updated in Gutenberg. This is the sort of problem that would hugely benefit from being detected early on, so that Gutenberg code can be updated to support the breaking changes.

One thing that could help here is regenerating the package-lock file in Gutenberg and committing it back to the repo when packages are published, so that any updated dependencies can be tested as part of the plugin release process.

Fixing dependency-related breakage also needs to be prioritised, and often during the Alpha part of the cycle developers are busy building out features so it’s easy for these bugs to slip between the cracks.

One thing that could mitigate this issue is nominating the release team (or at least the editor tech part of the team) for the next release before the current release ships. The overlap would allow for handover, so the new team is aware of any pending issues that didn’t get solved during the previous cycle, and able to coordinate fixing them, or at least not be tripped up by unexpected bugs. This means there will always be someone with ownership of the process to follow up with these issues.

Release cycle timing

Another point to consider is that the core workflow of committing changes to trunk before backporting them to the release branchbranch A directory in Subversion. WordPress uses branches to store the latest development code for each major release (3.9, 4.0, etc.). Branches are then updated with code for any minor releases of that branch. Sometimes, a major version of WordPress and its minor versions are collectively referred to as a "branch", such as "the 4.0 branch"., is an impediment to updating packages in trunk with the latest changes from Gutenberg until after the stable release ships. This is because the package updates for the release during Beta/RCrelease candidate One of the final stages in the version release cycle, this version signals the potential to be a final release to the public. Also see alpha (beta). will be committed to trunk, and those package versions have only the bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority. fixes necessary for the release. 

This may not be a huge problem though, as starting the sync process only after the stable release still leaves plenty of time for testing and solving any issues.

To summarise: what needs to be done in order to successfully start syncing core and Gutenberg earlier in the release cycle?

  • On the Gutenberg side, make sure all experimental/unstable code is made private and/or put behind a feature flag;
  • On the release organisation side, have some overlap between release teams so handover is easier and ownership of ongoing issues isn’t dropped.

Further suggestions, problems, feedback and ideas are very welcome!

Thanks to @andrewserong, @ramonopoly and @mamaduka for reviewing this post and @0mirka00 and @noahtallen for the package-lock suggestion 🙂

#block-editor, #gutenberg, #release-process