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 master 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:
- 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 two types of automated tests:
The functional test files for each WP-CLI repository are in the features/ directory. Each .feature file comprises one or more functional tests for a given feature (roughly organized by command).
A functional test can be as simple as:
Feature: Evaluating PHP code and files.
Scenario: Basics
Given a WP install
When I run `wp eval 'var_dump(defined("WP_CONTENT_DIR"));'`
Then STDOUT should contain:
"""
bool(true)
"""
Functional tests typically follow this pattern:
- Given some background,
- When a user performs a specific action,
- Then the end result should be X (and Y and Z).
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. Running the following as root in MySQL should do the trick:
GRANT ALL PRIVILEGES ON wp_cli_test.* TO "wp_cli_test"@"localhost" IDENTIFIED BY "password1";
Then, to run the entire test suite:
./vendor/bin/behat --expand
Or to test a single feature:
./vendor/bin/behat features/core.feature
More info can be found by using ./vendor/bin/behat --help.
Each repository is configured to run its tests on every code push. The wp-cli/automated-tests repository runs all tests for all repositories on a regular basis.
The unit test files are in the tests/ directory.
To run the unit tests, just execute:
./vendor/bin/phpunit
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!