Release Checklist Edit

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

Major/minor releases Major/minor releases

Updating WP-CLI 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 (ref).

Top ↑

Locking php-cli-tools version 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.

Top ↑

Updating the contributor list 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.

Top ↑

Updating the Phar build 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

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

3) Perform one last sanity check on the Phar by ensuring it displays its information

php wp-cli.phar --info

4) Commit the Phar and its hashes to the builds repo

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

5) Create a release on Github: 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

Top ↑

Updating the Debian build Updating the Debian build

1) Run this script:

2) Symlink the latest deb: ln -sfv php-wpcli_${VERSION}_all.deb php-wpcli_latest_all.deb

3) Commit file to builds repo

Top ↑

Updating the RPM build Updating the RPM build

The RPM build is generated by the wp-cli/rpm-build repo. A script is run on Travis to produce the build; then the RPM is pushed to the builds repo.

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

Top ↑

Updating the Homebrew formula 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:

  • Updating the url and sha256 here:
  • Making the commit with format “wp-cli 1.x.0”

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

shasum -a 256 v1.x.0.tar.gz

See and for background.

Top ↑

Updating the website Updating the website


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.

Top ↑

Regenerate command and internal API docs 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
cd handbook
wp handbook gen-api-docs
wp handbook gen-commands
wp handbook gen-commands-manifest
wp handbook gen-hb-manifest

Top ↑

Writing the release post Writing the release post

See prior release posts for a format to follow.

Top ↑

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

Top ↑

Bumping WP-CLI version again 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.

Top ↑

Patch releases 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.

3) Update VERSION on the release branch to the new release version.

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

5) Follow all of the other relevant release steps.