Skip to content

Latest commit

 

History

History
170 lines (99 loc) · 7.63 KB

release-checklist.md

File metadata and controls

170 lines (99 loc) · 7.63 KB

Release Checklist

This page describes the list of activities that developers must perform to produce a new release of WP-CLI.

Major/minor releases

Writing the release post

See prior release posts for a format to follow.

Regenerate command and internal API docs

Command and internal API docs need to be regenerated before every major release, because they're meant to correlate with the release.

To regenerate:

git clone git@github.com:wp-cli/handbook.git
cd handbook
wp handbook gen-all

Verify automated tests

Make sure the automated test suite is running correctly and passed. This represents the final build quality sanity check.

Updating WP-CLI

Make sure that the contents of VERSION are changed to latest.

Also update the WP-CLI version mention in the project's README.md (ref).

Locking php-cli-tools version

php-cli-tools is sometimes set to dev-master during the development cycle. During the WP-CLI release process, composer.json should be locked to a specific version. php-cli-tools may need a new version tagged as well.

Updating the contributor list

From the wp-cli/wp-cli project repo, use utils/contrib-list.php to generate a list of release contributors:

GITHUB_TOKEN=<token> wp --require=utils/contrib-list.php contrib-list --format=markdown

This script identifies pull request creators from wp-cli/wp-cli, wp-cli/handbook, and all bundled WP-CLI commands (e.g. wp-cli/*-command).

For wp-cli/wp-cli and wp-cli/handbook, the script uses the currently open release milestone.

For all bundled WP-CLI commands, the script uses all closed milestones since the last WP-CLI release (as identified by the version present in the composer.lock file). If a command was newly bundled since last release, contributors to that command will need to be manually added to the list.

The script will also produce a total contributor and pull request count you can use in the release post.

Updating the Phar build

  1. Create a git tag and push it.

  2. Create a stable Phar build:

    cd wp-cli-builds/phar cp wp-cli-nightly.phar wp-cli.phar md5 -q wp-cli.phar > wp-cli.phar.md5 shasum -a 512 wp-cli.phar | cut -d ' ' -f 1 > wp-cli.phar.sha512

  3. Sign the release with GPG. See wp-cli/wp-cli#2121

    gpg --output wp-cli.phar.gpg --sign wp-cli.phar

  4. Perform one last sanity check on the Phar by ensuring it displays its information

    php wp-cli.phar --info

  5. Commit the Phar and its hashes to the builds repo

    git status git add . git commit -m "Update stable to v1.x.0"

  6. Create a release on Github: https://github.com/wp-cli/wp-cli/releases. Make sure to upload the Phar from the builds directory.

    cp wp-cli.phar wp-cli-1.x.0.phar cp wp-cli.phar.gpg wp-cli-1.x.0.phar.gpg cp wp-cli.phar.md5 wp-cli-1.x.0.phar.md5 cp wp-cli.phar.sha512 wp-cli-1.x.0.phar.sha512

Verify Phar release artifact

Using some existing WP-CLI install, update to the latest release to verify the Phar release artifact works as expected.

$ wp cli update
You have version 1.4.0-alpha-88450b8. Would you like to update to 1.4.0? [y/n] y
Downloading from https://github.com/wp-cli/wp-cli/releases/download/v1.4.0/wp-cli-1.4.0.phar...
md5 hash verified: 179fc8dacbfe3ebc2d00ba57a333c982
New version works. Proceeding to replace.
Success: Updated WP-CLI to 1.4.0.
$ wp @daniel option get home
https://danielbachhuber.com

This represents a final sanity check that the Phar isn't corrupt in some way.

Updating the Debian and RPM builds

Both builds are produced by automated systems:

In either case, a script is run on Travis to produce the build, then the build artifact is pushed to the wp-cli/builds repo.

To generate a new build, trigger a Travis build on the repo (either by restarting an existing build or making some non-functional change).

Updating the Homebrew formula

WP-CLI's Homebrew formula is automatically updated with the Homebrew updater application. See Homebrew/homebrew-php/pull/4195#issuecomment-305442172.

If the updater application doesn't work for some reason, a pull request must be submitted to the Homebrew repo. This involves:

To generate the sha256 (replace x with the minor version):

wget https://github.com/wp-cli/wp-cli/archive/v1.x.0.tar.gz
shasum -a 256 v1.x.0.tar.gz

See https://github.com/Homebrew/homebrew-php/pull/1687#issuecomment-98408399 and https://github.com/Homebrew/homebrew-php/pull/3398#issuecomment-235896016 for background.

Updating the website

See https://github.com/wp-cli/wp-cli.github.com#readme

The current WP-CLI version will also need to be updated on the roadmap.

Please also tag a release of the website, so it's easy to correlate versions of the website.

Announcing

In addition to publishing the release post, a new release is announced in a few different ways:

  • WP-CLI Twitter account (with some scheduled follow-up tweets).
  • /announce slash command in the #cli Slack room.

Bumping WP-CLI version again

After all of the release steps are complete, make sure to bump VERSION again.

For instance, if the release version was 0.24.0, the version should be bumped to 0.25.0-alpha. Doing so ensure wp cli update --nightly works as expected.

Patch releases

Creating a patch release (e.g. 0.23.x) is bit different of a process than creating a major or minor release. At a high-level, here are the steps involved:

  1. Create a new release branch from the last tagged patch release:

    $ git checkout v0.23.0 Note: checking out 'v0.23.0' You are in 'detached HEAD' state. You can look around, make experimental changes and commit them, and you can discard any commits you make in this state without impacting any branches by performing another checkout. $ git checkout -b release-0-23-1 Switched to a new branch 'release-0-23-1'

  2. Cherry-pick existing commits to the new release branch.

Because patch releases should just be used for bug fixes, you should first fix the bug on master, and then cherry-pick the fix to the release branch. It's up to your discretion as to whether you cherry-pick the commits directly to the release branch or create a feature branch and pull request against the release branch.

  1. Update VERSION on the release branch to the new release version.

  2. PROCEED WITH EXTREME CAUTION. While the normal release process yields a built, fully-tested Phar file, the patch release process does not because the build system only pushes the Phar file on the master branch. As such, you need to manually build the Phar file for distribution.

    php -dphar.readonly=0 utils/make-phar.php wp-cli.phar --quiet

When you do so, run composer install to make sure you're using the appropriate Composer dependency versions for the release, not the master branch you normally work from. Once you've verified the built Phar, you'll need to copy it over to the builds repo.

  1. Follow all of the other relevant release steps.