WP-CLI follows a pull request workflow for changes to its code (and documentation). Whether you want to fix a bug or implement a new feature, the process is pretty much the same:
- Search existing issues; if you can't find anything related to what you want to work on, open a new issue in the appropriate repository so that you can get some initial feedback.
- Opening an issue before submitting a pull request helps us provide architectural and implementation guidance before you spend too much time on the code.
- Fork the repository you'd like to modify, either the framework or one of the command packages.
- See Setting Up for more details on configuring the codebase for development.
- Create a branch for each issue you'd like to address. Commit your changes.
- Push the code changes from your local clone to your fork.
- Open a pull request. It doesn't matter if the code isn't perfect. The idea is to get it reviewed early and iterate on it.
- Respond to code review feedback in a timely manner, recognizing development is a collaborative process.
- Once your pull request has passed code review, it will be merged into the default branch and be in the pipeline for the next release.
New to WP-CLI commands? You may want to start with the commands cookbook to learn more about how commands work.
There are three classes of repos you might want to edit:
- wp-cli/wp-cli is the framework implementation.
- wp-cli/scaffold-command is an example of a command implementation. There are many others.
- wp-cli/handbook contains documentation rendered in the handbook.
When submitting a pull request, there are several expectations to keep in mind.
Tests are required
Most of the time, we'll ask that functional or unit tests be added to cover the change. If it's a new feature, the pull request needs tests. If it's fixing a bug, the pull request needs tests.
See the documentation below for more information on writing and running tests.
Follow WordPress Coding Standards
While not yet strictly enforced, the WP-CLI project generally follows the WordPress Coding Standards. We may ask you to clean up your pull request if it deviates too much.
Please refrain from unnecessary code churn
Code refactoring should not be done just because we can. With a years-old codebase, there's an infinite number of best practice, readability, or consistency improvements that could be made. However, engaging on any of them has non-obvious costs: our time and attention, making Git history more difficult to review, etc. Any code changes should have clear and obvious value.
Contributions are atomic
To make it far easier to merge your code, each pull request should only contain one conceptual change. Keeping contributions atomic keeps the pull request discussion focused on one topic and makes it possible to approve changes on a case-by-case basis.
If you submit a pull request with multiple conceptual changes, we'll ask you to resubmit as separate pull requests.
Make regular progress on your contribution
Through our code review process, we'll work with you to make sure your pull request is ready for merge. But if changes are needed and we haven't heard from you in two weeks, we'll consider the pull request abandoned. Someone else may pick it up and make the changes required. Or it may be closed.
If you need to step away for any reason, make a comment on the pull request or the related issue so we can pick things up or put things on hold when needed.
If you haven't submitted a pull request before, you'll want to install WP-CLI for local development. Depending on whether you want to work on a particular command/package or on the entire project as a whole, the process is slightly different.
- Install Composer and hub if you don't already have them.
- Clone the git repository of the command/package you want to work on to your local machine. As an example for working on the
wp corecommand:hub clone wp-cli/core-command - Change into the cloned directory and fork WP-CLI:
cd core-command. - Install all Composer dependencies:
composer install - Verify WP-CLI was installed properly:
vendor/bin/wp --info
Within this package, you should preferably use vendor/bin/wp to run the command. Just using wp should work as well, but by doing that you might run the command through a different version of the framework and thus getting an unexpected result.
- Install Composer and hub if you don't already have them.
- Clone the WP-CLI git repository to your local machine:
git clone [email protected]:wp-cli/wp-cli.git ~/wp-cli - Change into the cloned directory and fork WP-CLI:
cd ~/wp-cli. If you are going to work on the core framework itself, runhub forkhere to create a pushable repository on GitHub. - Install all Composer dependencies:
composer install --prefer-source - Alias the
wpcommand to your new WP-CLI install:alias wp='~/wp-cli/bin/wp' - Verify WP-CLI was installed properly:
wp --info
Commands bundled with WP-CLI (e.g. wp scaffold plugin) will be editable from the vendor/wp-cli directory (e.g. vendor/wp-cli/scaffold-command). The --prefer-source flag when installing WP-CLI ensures each command is installed as a Git clone, making it easier to commit to.
Commands available for standalone installation (e.g. wp dist-archive) can be installed from source (e.g. wp package install [email protected]:wp-cli/dist-archive-command.git). Run wp package path <package-name> to find the appropriate directory to edit.
Importantly, you'll need to fork each repository in order to have an origin to push to. Run hub fork to fork a repository from the command-line:
$ cd vendor/wp-cli/scaffold-command
$ hub fork
Updating danielbachhuber
From https://github.com/wp-cli/scaffold-command
* [new branch] master -> danielbachhuber/master
new remote: danielbachhuber
$ git remote -v
danielbachhuber [email protected]:danielbachhuber/scaffold-command.git (fetch)
danielbachhuber [email protected]:danielbachhuber/scaffold-command.git (push)
Once you've done so, you'll have a fork in your GitHub account and new remote you can push to. If you didn't install hub, you'll need to fork the target repo through the web UI and manually add your fork as a remote.
There are three types of automated tests:
- code style sniffers, implemented using PHPCS
- functional tests, implemented using Behat
- unit tests, implemented using PHPUnit
The sniffers ensure that the code adheres to a given code style, to avoid unneeded discussions about less relevant details like spacing or alignments.
They also check for known sources of bugs and PHP compatibility problems.
To run the sniffs:
composer phpcs
To fix the errors and warnings that can be automatically fixed:
vendor/bin/phpcbf
WP-CLI uses Behat as its functional test suite. Stability between releases is an important contact WP-CLI makes with its users. Functional tests are different than unit tests in that they execute the entire WP-CLI command, and ensure they always work as expected.
Every repository has a features/ directory with one or more YAML-formatted *.feature files. Here's an example of what you might see:
Feature: Manage WordPress options
Scenario: Read an individual option
Given a WP install
When I run `wp option get home`
Then STDOUT should be:
"""
https://example.com
"""In this example:
Feature:documents the scope of the file.Scenario:describes a specific test.Givenprovides the initial environment for the test.Whencauses an event to occur.Thenasserts what's expected after the event is complete.
In a slightly more human-friendly form:
I have a WordPress installation. When I run
wp option get home, then the output from the command should be 'https://example.org'.
Essentially, WP-CLI's functional test suite lets you describe how a command should work, and then run that description as a functional test.
Notably, Behat is simply the framework for writing these tests. We've written our own custom Given, When, and Then step definitions (example, example).
Before running the functional tests, you'll need a MySQL (or MariaDB) user called wp_cli_test with the password password1 that has full privileges on the MySQL database wp_cli_test.
To override these credentials you can make use of the database credentials constants of wp-cli-tests
If your user has the correct permissions, the database can also be set up by running composer prepare-tests. This will create the database and the user and configure the necessary privileges. Note that this operation is not needed for every test run, it only needs to be run the first time for the initial setup.
Note: If you are using MySQL >= 8.0, you may experience inconsistencies with WP-CLI successfully connecting to the database. MySQL 8.0 changed the default authentication plugin and some clients (such as PHP) do not yet support this change. More information can be found on this blog post.
Then, to run the entire test suite:
composer behat
Or to test a scenario at a specific line:
composer behat -- features/core.feature:10
Or to test a single feature:
composer behat -- features/core.feature
Or to test a single feature with more verbosity:
composer behat -- features/core.feature --format pretty
To run only the tests that failed during the previous run:
composer behat-rerun
When writing new tests, to see which step definitions are available:
composer behat -- --definitions l
More info can be found by using composer behat -- --help.
The unit test files are in the tests/ directory.
To run the unit tests, execute:
composer phpunit
To run a specific unit test, you can use:
composer phpunit -- filter=<method name>
To run all tests in one go:
composer test
This will run all the tests that the package is set up to use, based on the presence of the respective configuration files.
Each repository is configured to run all of its active tests on every code push. The wp-cli/automated-tests repository runs all tests for all repositories on a regular basis.
Thanks! Hacking on WP-CLI should be fun. If you find any of this hard to figure out, let us know so we can improve our process or documentation!