Releasing the Performance Lab Plugin

This article describes how to publish a new release of the Performance Lab 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.

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.

Note that, as of now, this process will also release pending updates to the other standalone plugins managed through the WordPress/performance GitHub repository

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:


Review issues and milestones

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.

Top ↑

Branch off of trunk

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.

Top ↑

Create a new release branch

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:

git fetch origin
git checkout -b release/$VERSION_NUMBER origin/trunk
git push -u origin

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.

Top ↑

Communicate the change with other contributors

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.

Top ↑

Preparing the release

Top ↑

Create a local release branch

Before making any changes, create a new local branch based on the remote release branch release/$VERSION_NUMBER. From the terminal:

git fetch origin
git checkout -b publish/$VERSION_NUMBER origin/release/$VERSION_NUMBER

Make the following changes in that local branch.

Top ↑

Update the version number

The version number needs to be manually updated in the following places:

  • in the plugin headerHeader The 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 PHPPHP PHP (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. 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 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. or RCRelease Candidate A 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.

Top ↑

Update readme.txt

Run npm run readme -- --plugin="performance-lab" to update the readme.txt file with the release changelog. Or rather, to update the Performance Lab plugin and all standalone plugins, just run npm run readme.

After running the command, check the readme.txt file to ensure the new changelog for the release has been added. Also review its 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 -- --plugin="performance-lab" to verify version consistency and it should succeed. Do npm run versions to check all plugins.

Top ↑

Inspect changes to files in the release

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 SVNSVN Apache 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 released code are all centrally managed through SVN. status and diff for each plugin (example). Add this as a comment on the pull request you’ll open below. (TODO: This is pending PR merge.)

Top ↑

Ensure pending standalone plugin releases are ready

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.

Top ↑

Open a pull request

Push your local branch to the GitHubGitHub GitHub 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. 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).

git push -u origin
gh pr create --title "Prepare $VERSION_NUMBER release" --base "release/$VERSION_NUMBER" --milestone "performance-lab $VERSION_NUMBER" --label "skip changelog" --label "Infrastructure" --label "[Type] Documentation"

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).

As usual, make sure to request a review from at least 2 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

Top ↑

Publishing the release

Top ↑

Notify maintainers and review release branch

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.

Top ↑

Create the release tag

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.

Please see the article on releasing a standalone plugin for additional information.

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.

Top ↑

Review and test the deployment

Once a new version is released on GitHub, the plugin will be deployedDeploy Launching code from a local development environment to the production web server, so that it's available to visitors. to the repository. The deployment workflow progress can be tracked here.

At this point, test the update process from your WordPress site, getting the plugin from The 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. The main aspects to test at this point are:

  • Install or update the plugin via, ZIP upload, WP-CLIWP-CLI WP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is, etc.
  • Test the plugin on different WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. versions supported.
  • Test the plugin on a multisiteMultisite Multisite 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. 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.

Top ↑

Wrapping up the release

Top ↑

Update trunk

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 UIUI UI 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 CLICLI Command Line Interface. Terminal (Bash) in Mac, Command Prompt in Windows, or WP-CLI for WordPress. command to open the PR:

gh pr create --title "Post $VERSION_NUMBER release merge" --base=trunk --head="release/$VERSION_NUMBER" --milestone "performance-lab $VERSION_NUMBER" --label "skip changelog" --label "Infrastructure" --label "[Type] Documentation"

Consider linking to the previous such PR, for example #1134 and #1230.

Top ↑

Close the release

As a last action, close the GitHub milestone for the release. Make sure that all issues in the milestone are closed.

For any standalone plugin that an update was published for, please close the relevant GitHub milestones as well.

Don’t delete the release branch since that branch can be used to later create patch releases from the same state of the codebase.

Last updated: