Releasing Minor Versions

So, you wanna ship a minor version of WordPress? Okay, maybe you don’t want to. Perhaps you need to ship a minor version of WordPress. From time-to-time, we ship security and maintenance fixes to our users. There’s a lot involved with shipping these releases, as documented below. If you’ve been through the release process before and see something missing please add it.

Before Release Before Release

Before you’ve decided to release, there are a few things to consider [TODO: Add more to this section]:

  • Is this release because of a security fix?
  • Will this release contain only security fixes?
  • What maintenance fixes should go into the release? Have those maintenance fixes been committed to trunk?

Depending on the focus of the minor release (security, maintenance, or both), there are a few things to consider.

Security Security

In the case of a purely security release, all patches should be created well ahead of time. Different patches may be necessary for trunk and stable branches. Currently, we make an effort to back port patches to all versions of WordPress that support autoupdates (3.7+). However, back porting patches is not always possible and those versions of WordPress are not officially supported as a result.

Once you’ve worked up a patch for the latest stable branch, ask for external testing and support from the rest of the security team. Many members of the security team work for companies with large WordPress installations and can test the patch on their systems to see if there are edge cases that your patch does not consider.

Regardless of if you get external testing, all patches should be well-tested and receive sign off from the WordPress Security Team at least five days ahead of the scheduled release date. It’s incredibly important to get this feedback early on as security fixes do not have a lot of time to bake on trunk.

For security fixes reported by third-parties, get information on how they would like to be credited. The announcement post on credits third-parties as requested.

On release day, if a test fails or a security fix is no longer working properly, punt. Do not attempt last minute fixes. Either reschedule the release or do not include the fix in the release. Last minute fixes can lead to major bugs.

Are your security fixes ready? Awesome. Got maintenance fixes? Keep reading. If not, skip the next section.

Top ↑

Maintenance Maintenance

Unlike security fixes, maintenance fixes can land on trunk any time. There’s a Trac query dedicated to tickets targeted at the next minor release. If you’re considering a maintenance release, be sure to run through those tickets in addition to any tickets in mind. Once you’ve determined that your release is a maintenance release, start getting patches landed on the branches. The sooner, the better, so there’s less of a rush at the end.

Ideally, all patches land at least 48 hours before release and a release candidate is built. This can be a formal release candidate or a nightly build that includes all fixes. If you build a release candidate, post about it on make/core along with a list of what fixes are in the release.

Top ↑

Both Both

Regardless of which kind of release you’re planning, there are a number of things you need to do.

  • Notify the Akismet team a few days ahead of time. If they have a plugin release coming soon, it’s good for us to be able to include an updated version, so users aren’t being prompted to updated Akismet as soon as they install WordPress. Here’s an example of a commit to build.svn that bumps the Akismet external to the latest version.
  • You’ll want to notify hosts that a release is coming a couple of days ahead of time. Three days is the recommended time frame, but is not always possible depending on release timeline. The security team can give you information on the contents of this email. This email should not go out until all security patches are ready (if a security release).
  • If there will be string changes in your release (hopefully not!), notify the polyglots team ahead of time. Normally, @ocean90 will take care of this for you, but ensure he’s aware.
  • Do a diff on the src/ directory between the last release tag and the release branch and confirm there are no new files introduced, since these will often break automatic upgrades.
  • A news post is needed for the news blog. Generally speaking, you should start this at least a day ahead of time (the more time, the better). You can copy the format from previous releases. Be sure to grep logs to get a complete list of all contributors to the release. The list of props can most efficiently be gathered by someone who has access to a sandbox (like @ocean90, @obenland, or @pento) to run wporg/bin/core/props-parser.php.
  • Alert the systems team (e.g. @vnsavage, @pyry, @sysmonk, @seanosh, or @abbe) about your release so they can plan to have someone available in case there are any issues. The sooner you’ve set a time for release, the sooner you can do this.
  • 12 hours before release (or before), you’ll need to lower the TTL in the update API to 60 minutes. This means that, by the time you release, all WordPress installations will be checking for a new version of WordPress every hour. To lower the TTL, update the WP_CORE_SHORT_API_TTL_VERSION constant in versions.php to the impending release version number. This file requires access to a dotorg sandbox, so one of them must be on hand for this.
  • Prepare Codex pages for each version you intend to release, using the Wiki Template of Release (directions are included on that page). If your release is security-related, these pages can be mostly blank until the actual release day, but need to exist as we link to them in WordPress itself.

Now that you’ve done all of that, it’s on to release day.

Top ↑

Release Day Release Day

You’ve made it. Release day can be stressful. The best way to survive release day is to stay calm. Things will go wrong. It’s okay, just regroup and keep moving forward. Here’s a list of things that need to get done on release day:

  • [This is not relevant to minor releases.] The relevant credits file needs to be updated to list any new contributors. That files lives in the meta repository.
  • If you’re running a security release, security patches need to be committed to all relevant branches.
  • Version bumps need to be committed on all relevant branches. Here’s an example (please ignore the readme.html bump). Any core committer can do this step. When committing a version bump on the most recent branch please update both the version.php and about.php files. The package.json file should already be updated for the current branch but will need to be updated for any previous branches (example).
    • package.json has a single simple bump to X.Y.Z.
    • version.php has one bump to X.Y.Z-src. Note the -src suffix that should always be included when committing to develop.svn.
    • about.php needs a number bump to Z in the “Maintenance and Security Release(s)” heading and a paragraph added describing the changes in the release, using existing strings as defined at the bottom. These strings differ from branch to branch, so please make sure to use the ones from the correct version. It is easiest to copy and paste the appropriate paragraph from elsewhere. If this is the first minor release for a branch, there is also a wrapping div and the aforementioned h3 to add after the nav tabs. Make note of the possible string combinations for single and multiple security and/or bug fixes. Checkout a more complete explanation of the differences.
    • Prepare these changes well in advance and ask for a review. This will help avoid hold-ups during the release process. The version bump and about page can be committed together, they do not need to be separate.
  • The release packages need to be built in mission control, from the branch of each version being released, as the tag for the release isn’t created until later. Once it’s packaged, it needs to be tested well, including manually testing updates. (How do you do that? Checkout the docs.)
  • Autoupdates need to be enabled in the versions.php file, located in the dotorg repository. (This file requires access to a dotorg sandbox, so one of them must be on hand for this.) To enable autoupdates, set the WP_CORE_LATEST_RELEASE constant to be the new version number. You should also update the array in wporg_get_versions() to add all of the new versions. The keys of the array in wporg_get_version_equivalents() should match all of the new versions, and the corresponding old version should be added to the array of old versions.
    • The percentage on offer can be lowered in this file as well, if our systems are having trouble serving so many updates. Generally, they’ll ask us to lower it to 50% and raise it from there after 30-45 minutes. To alter the percentage, change the WP_CORE_AUTOUPDATE_PERCENT constant.
  • The post needs to be published.
  • Alert make/polyglots that you have released. Some locales produce their own builds instead of relying on the automatic builds and need to package things on their own. Here’s an example. (Again, @ocean90 normally does this for you.)
  • On all branches, the release needs to be tagged once updates are successfully flowing. Many people run releases from SVN and rely on the tags to do that. Tagging can be completed by using following commands (be sure to update with your relevant branch and release): svn cp -m "Tag 4.2.3"
    • If you’ve double- and triple-checked to ensure that is the repository root for your checkout, you can use the ^ shortcut, which would result in this command: svn cp ^/branches/4.2 ^/tags/4.2.3 -m "Tag 4.2.3"
  • Update all Codex Version pages with the file diff list and the link to the news post.
  • Update the Codex CurrentVersion Template with the new version.
  • Add new versions to the Codex WordPress Versions page.
  • Add new revisions to the polyglots handbook release revisions section.
  • If there were any changes to the REST API, update the REST API changelog over at dev hub.
  • In Trac, create (a) new milestone(s) for X.Y.Z+1 and mark the old milestone(s) as completed. This must be done by a Trac admin.
  • Do the same in Security Trac, or ask a Security Team member to do this. This must be done by a Security Trac admin.
  • In Trac, create a new version for each X.Y.Z+1 release (including branches with backports). Delete the date from the Released date field. This too must be done by a Trac admin.
  • Bump the latest stable branch version to X.Y.Z+1-alpha-$REVNUM-src along with the corresponding package.json and readme changes.

Top ↑

Schedule Schedule

Assuming you’re following the instructions above and have an ideal schedule (all the time in the world), you’ll want to use the following schedule:

When? What?
T-7:00:00 Triage all targeted tickets.
T-5:00:00 All security patches created, tested, and cleared by the WordPress Security team.
T-4:00:00 Commit all non-security patches to the relevant branch(es).
T-3:00:00 Notify hosts that a release is coming.
T-1:00:00 Create the blog post (as draft).
T-0:12:00 In the update API, lower the TTL to 60 minutes. (WP_CORE_SHORT_API_TTL_VERSION constant in version.php.)
T-0:05:00 Commit security patches and run unit tests and security tests.
T-0:00:31 Version bumps on all relevant branches.
T-0:00:30 Build the release package in mission control. Test package and manually test updates.
T-0:00:00 Turn on autoupdates. (WP_CORE_LATEST_RELEASE constant, and the wporg_get_versions() and wporg_get_version_equivalents() functions in version.php.)
T+0:00:01 Post the blog post.
T+0:00:15 Update credits (before or after release).
T+0:01:00 Autoupdates complete (for the most part).
T+0:01:00 Tag the releases. Many people run WordPress from SVN and need a tagged release to deploy.

Top ↑

Extras Extras

Selecting About Page Strings

There are 5 options for strings to choose from for the About page paragraph describing the release.

  • If there is 1 security issue and no bug fixes: <strong>Version %s</strong> addressed one security issue.
  • If there are more than one security issues and no bug fixes: <strong>Version %s</strong> addressed some security issues.
  • If there are one or more bugs, _n() is used with the strings <strong>Version %1$s</strong> addressed %2$s bug. and <strong>Version %1$s</strong> addressed %2$s bugs. to the determine the proper string for the locale.
  • If there is 1 security issue and one or more bug fixes, _n() is used with the strings <strong>Version %1$s</strong> addressed a security issue and fixed %2$s bug. and <strong>Version %1$s</strong> addressed a security issue and fixed %2$s bugs. to determine the proper string for the locale.
  • If there are more than one security issues and one or more bug fixes, _n() is used with the strings <strong>Version %1$s</strong> addressed some security issues and fixed %2$s bug. and <strong>Version %1$s</strong> addressed some security issues and fixed %2$s bugs. to determine the proper string for the locale.

Defer to other recent point releases for examples on how the strings change along with the numbers. Check the strings and have them reviewed before commit.

Testing Package Builds

There are a few ways to test package builds, but using WP-CLI is a fast, effective way. Here’s a run down of commands you can use to test upgrades between versions. This example will be testing between 4.5.2 and 4.5.3 and will assume that some version of WordPress >= 3.7 is already installed.

  • $ wp core download --version=4.5.2 --force This will retrieve the version you want to start from.
  • $ wp core update-db Get the database where it needs to be.
  • $ wp core update Update to the package you’re testing.
  • $ wp core update-db Make sure any database updates run.

Then check your test site to make sure everything is well. Happy upgrade testing!