Pull Requests Edit

WP-CLIWP-CLI WP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is http://wp-cli.org/ https://make.wordpress.org/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:

  1. 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.
    1. Opening an issue before submitting a pull request helps us provide architectural and implementation guidance before you spend too much time on the code.
  2. Fork the repository you’d like to modify, either the framework or one of the command packages.
    1. See Setting Up for more details on configuring the codebase for development.
  3. Create a branch for each issue you’d like to address. Commit your changes.
  4. Push the code changes from your local clone to your fork.
  5. 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.
  6. Respond to code review feedback in a timely manner, recognizing development is a collaborative process.
  7. 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:

Expectations

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 StandardsWordPress Coding Standards The Accessibility, PHP, JavaScript, CSS, HTML, etc. coding standards as published in the WordPress Coding Standards Handbook. May also refer to The collection of PHP_CodeSniffer rules (sniffs) used to format and validate PHP code developed for WordPress according to the PHP 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 GitGit Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Git is easy to learn and has a tiny footprint with lightning fast performance. Most modern plugin and theme development is being done with this version control system. https://git-scm.com/. 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.

Top ↑

Setting up

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.

Top ↑

Working on a specific command/package

  1. Install Composer and hub if you don’t already have them.
  2. 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 core command: hub clone wp-cli/core-command
  3. Change into the cloned directory and fork WP-CLI: cd core-command.
  4. Install all Composer dependencies: composer install
  5. 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.

Top ↑

Working on the project as a whole

  1. Install Composer and hub if you don’t already have them.
  2. Clone the WP-CLI git repository to your local machine: git clone git@github.com:wp-cli/wp-cli.git ~/wp-cli
  3. Change into the cloned directory and fork WP-CLI: cd ~/wp-cli. If you are going to work on the coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. framework itself, run hub fork here to create a pushable repository on GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/.
  4. Install all Composer dependencies: composer install --prefer-source
  5. Alias the wp command to your new WP-CLI install: alias wp='~/wp-cli/bin/wp'
  6. 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 git@github.com: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 git@github.com:danielbachhuber/scaffold-command.git (fetch)
danielbachhuber git@github.com: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 UIUI UI is an acronym for User Interface - the layout of the page the user interacts with. Think ‘how are they doing that’ and less about what they are doing. and manually add your fork as a remote.

Top ↑

Running and writing tests

There are three types of automated tests:

  • code style sniffers, implemented using PHPCS
  • functional tests, implemented using Behat
  • unit tests, implemented using PHPUnit

Top ↑

Code style sniffers

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 PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. http://php.net/manual/en/intro-whatis.php. compatibility problems.

To run the sniffssniff A module for PHP Code Sniffer that analyzes code for a specific problem. Multiple stiffs are combined to create a PHPCS standard. The term is named because it detects code smells, similar to how a dog would "sniff" out food.:

composer phpcs

To fix the errors and warnings that can be automatically fixed:

vendor/bin/phpcbf

Top ↑

Functional tests

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.
  • Given provides the initial environment for the test.
  • When causes an event to occur.
  • Then asserts 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).

Top ↑

Creating a test database

Before running the functional tests, you’ll need a MySQLMySQL MySQL is a relational database management system. A database is a structured collection of data where content, configuration and other options are stored. https://www.mysql.com/. (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 pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party and some clients (such as PHP) do not yet support this change. More information can be found on this blog post.

Top ↑

Running the test suite

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.

Top ↑

Unit tests

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>

Top ↑

Running all tests in one go

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.

Top ↑

Finally…

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!

Last updated: