The WordPress CoreCoreCore is the set of software required to run WordPress. The Core Development Team builds WordPress. Performance Team is dedicated to monitoring, enhancing, and promoting performance in WordPress core and its surrounding ecosystem. We build and manage the Performance Lab plugin, a collection of performance-related “feature projects” for WordPress core.
This article describes how to publish a new release of the Performance Lab pluginPluginA 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 WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party.
The WordPress Performance Team is currently revising the process for releasing Performance Lab and its standalone plugins. As such, it is expected that some of the steps outlined in this article may change in the future.
The following instructions will refer to $VERSION_NUMBER as a variable containing the version number. You can facilitate running the shell commands below by populating this environment variable with the next version number:
Before you get started, make sure that no issues or PRs remain in the milestone for the release, with the exception of a single issue dedicated to the release process itself. Also review the completed issues and merged pull requests that have no milestone in case the milestone assignment was missed.
The cutoff point for a release specifies the point in time where no new features or enhancements should go into the release, only critical fixes. There is no hard rule for when this point should be reached, but the loose guidance is around a week before the tentative release date.
At the cutoff time, create a new remote branch release/$VERSION_NUMBER from the latest trunk. For example, if the version number is 1.2.0, name the branch release/1.2.0. From the terminal you can do:
This should be done a few days before the release. Keep in mind that any changes merged into trunk after the release branch has been made may need to be cherry-picked into the release branch. Alternatively, once the release branch has been made, pull requests can target the release branch instead of trunk; the changes will end up in trunk once the release branch is merged back into trunk at the end of the release process.
Once the release branch exists, any pull requests that are relevant for that upcoming release need to be based on the release branch instead of trunk. For relevant pull requests that are already in progress at the time of creating the branch, change the base branch accordingly.
Most importantly, immediately communicate with the other plugin contributors that the release branch now exists, e.g. by updating the overall release issue with a new comment or leaving a note in the #core-performance Slack channel. This way other contributors should be aware that critical pull requests related to that upcoming release need to be based on the release branch instead of trunk.
The version number needs to be manually updated in the following places:
in the plugin headerHeaderThe header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. in load.php
in the PHPPHPPHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. https://www.php.net/manual/en/preface.php. constant in load.php
in the readme header in readme.txt
in a new first-most changelog entry (see below)
In addition to those locations, run the npm run since command to replace any occurrence of @since n.e.x.t with the version number located in the readme.txt file’s Stable tag. This ensures any code annotated with the “n.e.x.t” release will now have its proper version number on it. The only exception to this are pre-releases, such as a betaBetaA 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. or RCRelease CandidateA beta version of software with the potential to be a final product, which is ready to release unless significant bugs emerge.: For those, the stable version number should be used. For example, if the milestone is 1.2.0-beta.2, the version in e.g. @since annotations in the codebase should still be 1.2.0.
Run npm run readme to update the readme.txt file for each plugin with its respective release changelog derived from the plugin’s milestone.
After running the command, check the readme.txt files to ensure the new changelogs for the releases have been added. Also review the changelog entries for whether they make sense and are understandable. If any of the entries needs to be updated, open the corresponding pull request and update its title to a more accurate message, then re-run the readme command to have it updated in readme.txt. Make sure that no unexpected changelog entries are present. Other contributors will later review it, so don’t worry too much if you are unsure about a changelog entry.
At this point, you should be able to run npm run versions to verify version consistency and it should succeed.
To make sure that all of the expected files are present and the expected changes are present, do a diff between the released plugins and the pending releases. You can use the npm run generate-pending-release-diffs --silent command to generate a markdown document that includes an SVNSVNApache Subversion (often abbreviated SVN, after its command name svn) is a software versioning and revision control system. Software developers use Subversion to maintain current and historical versions of files such as source code, web pages, and documentation. Its goal is to be a mostly compatible successor to the widely used Concurrent Versions System (CVS). WordPress core and the wordpress.org released code are all centrally managed through SVN. https://subversion.apache.org/. status and diff for each plugin (example). Add this as a comment on the pull request you’ll open below.
Make sure that the Stable tag is bumped for each plugin with changes that needs to be released!
As the eventual Performance Lab release will also publish any pending standalone plugin updates managed through the WordPress/performance GitHub repository, it is crucial to ensure that the code for any plugins that meet those requirements is in fact ready to be released in the release branch before tagging the new Performance Lab release.
Please ensure that any plugins with pending version updates are ready to be published, per the requirements outlined in the article for releasing standalone plugins, which are the same as releasing the Performance Lab plugin since it is also now just one of the plugins in the Performance monorepo.
Push your local branch to the GitHubGitHubGitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ repository and open a pull request against the release branch release/$VERSION_NUMBER. Make sure to add the minimum necessary labels Infrastructure, [Type] Documentation, and skip changelog (since we don’t want this PR’s title to show up in a changelog).
Set the PR to fix the issue (that should already exist) for preparing the release. Add a link to the previous such pull request to refer back to (e.g. #1129). Consider adding ZIP builds of the plugins in a comment on the PR to facilitate testing (example). These can be generated via npm run build-plugins:zip.
As usual, make sure to request a review from at least two plugin maintainers. Once approved, the pull request can be merged.
This would be good to do as close to the chat as possible, or even as the first task that you do during the chat
Once the above pull request has been merged, let the other maintainers know on Slack that no new commits or pull requests must be added to the release branch due to the release process. Then, make sure that all GitHub workflows successfully pass for the release branch.
This step will actually publish the Performance Lab update and any pending standalone plugin updates managed through the WordPress/performance GitHub repository. Please ensure all of the pending updates are ready to be published.
To publish the Performance Lab release, create a new release tag for the plugin on GitHub. The release tag should use the version number as its name, and it should be created from the release branch release/$VERSION_NUMBER. Finally, add the changelog (it can be found in the readme.txt file) to the release description and create the release.
At this point, test the update process from your WordPress site, getting the plugin from wordpress.orgWordPress.orgThe community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/. The main aspects to test at this point are:
Install or update the plugin via wordpress.org, ZIP upload, WP-CLIWP-CLIWP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is http://wp-cli.org/https://make.wordpress.org/cli/, etc.
Test the plugin on different WordPress coreCoreCore is the set of software required to run WordPress. The Core Development Team builds WordPress. versions supported.
Test the plugin on a multisiteMultisiteMultisite is a WordPress feature which allows users to create a network of sites on a single WordPress installation. Available since WordPress version 3.0, Multisite is a continuation of WPMU or WordPress Multiuser project. WordPress MultiUser project was discontinued and its features were included into WordPress core.https://codex.wordpress.org/Create_A_Network. environment as well.
Make sure there are no PHP errors or warnings and that the high-level functionality works.
After successful testing, inform the other maintainers on Slack that the new release has been published and that committing may continue.
Since the release branch was branched off the main branch trunk, the latter now needs to be updated to include any additional changes made to the release branch since.
To do that, open a pull request from the release branch to trunk (can be done via GitHub UIUIUI is an acronym for User Interface - the layout of the page the user interacts with. Think ‘how are they doing that’ and less about what they are doing.) and ask two maintainers to approve it. The code in this pull request does not need to be closely reviewed since it was already approved prior, so this is mostly a formal approval. Here is the CLICLICommand Line Interface. Terminal (Bash) in Mac, Command Prompt in Windows, or WP-CLI for WordPress. command to open the PR: