Contributing to WP-CLI

Drawing of female freelancer sitting in front of their laptopDoes WP-CLI save you effort and time while working on the sites you manage?
Do you use WP-CLI to automate your infrastructure or deployments?
Do you feel positive about the WP-CLI project and its mission?
This guide will tell you about the many possibilities you have to get involved and play a role in this official WordPress team.

Introduction

First of all, thank you very much! If you’ve read this far, it must mean you are taking the initiative to contribute to WP-CLI. It’s because of you, and the community around you, that WP-CLI is such a great project. It not only makes for a fabulous tool people can use in a reliable manner, it also makes for a fun and rewarding project to collaborate on.
Contributing can take many forms, and we will discuss the most prominent ones. Before we start, though, here’s a list of what contributing is not:
  • Contributing is not limited to code.
  • Contributing does not require committing to a specific amount of time.
  • Contributing does not require expert knowledge in any of the areas it touches.
Drawing of a man hanging from a rope to work on a computer.We encourage you to contribute in the way that best fits your interests and abilities. If at any point, you’re not sure how to proceed with whatever you are doing or feel you’re in over your head, help & support is just a chat message away! Please don’t hesitate at any point to just ask questions or let us know about the issue you’re facing.
Also, please do know that there are no expectations you need to fulfill or requirements you need to meet. This is meant to be an enjoyable, collaborative experience. So make sure you don’t put pressure on yourself and rectify your course of action if you feel that you’re not actually enjoying it anymore.
Now, with that clarification out of the way, let’s try to cover some of the most common ways of contributing to WP-CLI.

Spreading the message

Drawing of a woman watering plants that look like social media network logos.Not everyone knows about WP-CLI or how it can help improve how you interact with a WordPress site.
There are multiple ways of how you can help spread the message about WP-CLI:
  • Post clever uses as tips to social media (tagging @wpcli on Twitter is always appreciated).
  • Submit conference talks about usage and best practices.
  • Publish tutorials on your blog.
  • Give a demo at your local meetup.
Note: You can request free stickers to distribute at events → read about the requirements.

Supporting users

Drawing of a typing indicator in a chat system.A great way to learn more about WP-CLI yourself and to help other people make progress is to jump into one of the support channels and try to answer questions other people have posted. Doing the detective’s work, understanding how the moving pieces work and finally getting to the bottom of a user’s problem can be very rewarding, and you learn all kinds of internal details along the way.
There are three main avenues where people can request support:
Any open issue/question/thread you can find in these locations are open for anyone to contribute an answer or to ask further questions to help diagnose the issue.

Improving documentation

Drawing of a woman filing notes.Is documentation your strength? Take a look at the currently open documentation issues and see if you can tackle any of those, or create a new issue if you’ve read through the documentation and found it lacking in a specific area.
There are a couple different types of documentation currently part of WP-CLI:
  • Documentation for individual WP-CLI commands (anything underneath developer.wordpress.org/commands) is contained in the PHPDoc for each command. This means that to edit the documentation for a command, you will need to edit the file that actually provides the functionality for that command. The web documentation is generated from these files at the time of release, so you may not see your changes until the next release.
  • Individual documentation pages (anything under make.wordpress.org/cli/handbook) can be edited by contributing to the handbook repository on GitHub. You don’t necessarily need to navigate the Github repo though; any page that is part of this repository will have an Edit link in the top right of the page which will take you to the corresponding file on GitHub. Just clicking on that link brings you to a live editor which will generate a pull request out of your changes.

Localization

Drawing of multiple windows showing the same basic content.WP-CLI is in a special position when it comes to localization. Its main output is not supposed to be localized, as it is used for scripting purposes. If your scripts depend on a given string to be printed to the console, translating that string into a different language will, of course, break these scripts.
What should be translated, though, is the different types of documentation we have. Unfortunately, we are currently lacking the infrastructure support on make.wordpress.org/cli to properly support translated versions of the handbook or command reference.
What can be translated right now and is open for contributors is the README file shown as the frontpage on wp-cli.org. The different language versions can be found in subfolders in the wp-cli/wp-cli.github.com repository. Please use the English source version as the reference source, as it is the only one to be guaranteed to be up-to-date at any time.

Reporting security issues

Drawing of a man manipulating a security shield.Don’t publicly disclose a security issue you’ve just found!
The WP-CLI team and the WordPress community take security bugs seriously. We appreciate your efforts to responsibly disclose your findings and will make every effort to acknowledge your contributions.
To report a security issue in a responsible way, please visit the WordPress HackerOne program. You will be able to submit details about the security vulnerability in a confidential way, to avoid malicious users immediately exploiting the vulnerability on live sites. You will be contacted by the WordPress security team about next steps as soon as possible.

Reporting a bug

Drawing of a computer screen showing an alert.Think you’ve found a bug? We’d love for you to help us get it fixed.
Before you create a new issue, you should search existing issues (*) to see if there’s an existing resolution to it, or if it’s already been fixed in a newer version of WP-CLI. You should also check our documentation on common issues and their fixes.
Once you’ve done a bit of searching and discovered there isn’t an open or fixed issue for your bug, please follow our guidelines for submitting a bug report to make sure it gets addressed in a timely manner.

Requesting a new feature

Drawing of a man rearranging post-its on a whiteboard.To request a new feature, please create a new issue in the issue tracker of the wp-cli/ideas repository.
This is the very first step that any new functionality should take. It will be further fleshed out within this issue until a decision has been made about whether the feature is a good fit for the official WP-CLI bundle and how the technical implementation should be handled. At that point, the issue will move into the repository where its code will finally reside.

Working on the code

Before you can start writing code, you need to decide what you plan on working on.
  • Good first issues
    To get your feet wet with working on the WP-CLI codebase, you should star with one of the issues that are marked as good-first-issues. These issues usually require less historical knowledge and are very limited in scope and complexity. Often times, you’ll find the proper approach to solve the issue directly explained within the issue conversation.
  • Fixing a bug
    Even though we spend a lot of time writing tests and reviewing code, we cannot completely avoid bugs in a codebase of this complexity.
    If you want to see a list of known bugs and help fix them, you can use this GitHub search (*).
  • Implementing a new feature
    You can find the collection of submitted feature requests in the issue tracker of the wp-cli/ideas repository. There are labels that define what the current state of a feature request is:
    • state:approved: This feature request has already been accepted in principle and only needs someone that can invest the time to make it happen.
    • state:considering: This feature request seems to be useful and a good fit for the project, but additional discussion and fleshing out is needed before a final decision can be made.
    • state:unlikely: This feature request was deemed not to be a good fit for the project. The reason for this is probably stated in the issue conversation. An implementation of this feature is unlikely to be accepted for bundling into an official release. Note: This might still be a useful third-party command in its own right.
    • In case there is no state label associated with the issue, it probably needs more extensive discussion still to find out how it relates to the official WP-CLI code.
Drawing of a software developer working on their laptop.Once you’ve decided to commit the time to seeing your pull request through, please follow our guidelines for creating a pull request to make sure it’s a pleasant experience. See “Setting up” for details on making local modifications to WP-CLI. Keep in mind pull requests are expected to have tests covering the scope of the change. Read through our code review guidelines for a better understanding of how your pull request will be evaluated.

Anything missing?

Hopefully, this short guide has presented many different ways of how users and fans of WP-CLI can contribute to the project’s continued success.

If you think we missed anything, please tell us so in the comments below! We’d love to hear your feedback and are curious about yet other ways of contributing to WP-CLI.


(*) Link requires you to be logged into Github, otherwise it will show a 404.
All images provided by unDraw and licensed under the MIT license.

#contributing

WP-CLI Hack Day

We’re currently planning the first ever WP-CLI Hack Day! 🤓🎈

On 🗓 Friday, 20th July 2018 we’ll officially kick off the WP-CLI Hack Day at 🕗 08:00 CEST. From that point on, I’ll be generally available in Slack #cli channel and on the GitHub wp-cli organization to onboard new contributors, help people pick issues to work on and remove hurdles that keep them from finishing their PRs. This will continue more or less without interruption during the entire event.

From 🕓 16:00-18:00 CEST we’ll have an open video chat that everyone can join, where we can discuss remaining issues live and chat about the progress we’ve made. This extended video chat session will then conclude the event. Shortly after 🕕 18:00 CEST, I will post a make/cli blog post about the progress we were able to make during the allotted time frame.

The 🎯 goal for this first WP-CLI Hack Day is both simple and ambitious:

Finish the day with 2️⃣0️⃣ pull requests that have been merged during the event ❗️

Everyone is welcome to participate! This event is supposed to be fun and inspiring, and we expect people to help each other make progress along the way.

 

Let’s make this happen! 👍

 
Update: the official hashtag for the event is #hackwpcli 📣


Note on times:

The times are in CEST timezone to fit my schedule. ( ⇒ See time range and copy into calendar )

I’m fully aware this is not ideal for everyone around the globe. Hopefully, this first try at such an event will be a big success, and we’ll try it again with more helpers and an extended time zone at a later date.

#hack-day

GPG Signature Change

Starting from May 31st, 2018 (from WP-CLI version 1.5.1 onwards), the GPG key that is used to sign the releases has changed.

Here’s the new public key for signed releases:

-----BEGIN PGP PUBLIC KEY BLOCK-----

mQENBFsQEBkBCADfGAhxQ71XaIk31SjD8dNH3uVNtPh/2SIIhYbObMvEG6uoMucP
t3jCsnkh/veKBkJ+HJ/XcARGoFYdaCZo5PTORBWOwHmeWPbu7aiAM4v3EKPc8wZP
jabtEejwZrRFlSlAu5YL25ldz5KNgvGOBdje9jUi2iovQ4lfjMEuH2sXhmDQPbDW
22Fb2xinvmlnyf5kJn9ADiWm6VEnaNvaL96TCC1iUrMJmYI0m29j2sVbKJIq8ZBO
CgtY4llPC7QskWw8VXEAq2WnQeZMVLqxOSoRDy/qUvw0RR+DfiXsrHjBxAH4uvHK
zUdnMl1Qbh2A/rfcsIaJubXg5pUXwF7TCvSPABEBAAG0JVdQLUNMSSBSZWxlYXNl
cyA8cmVsZWFzZXNAd3AtY2xpLm9yZz6JAU4EEwEIADgCGwMFCwkIBwIGFQgJCgsC
BBYCAwECHgECF4AWIQRjr3qhUGfAVhb93YijoujyJvC8BgUCWxAQ7AAKCRCjoujy
JvC8BmYTCACPEYQr89U/H/iQcI012UaOSLYLx+Qj9oA7p9gv2mZSBHNSijzhnizo
QBEg7q7BXF8B8UqL9ZhUWfG9PiR8kkFbBN1sIY0RM5cFltb3cJthVH4ZV8SUiGW6
zIOd8m5JXVnekmZyJFpufxDHms6F3Z2RNUbdZSp2Mj+5p/a4GtJhfGGpfYBbXOxG
gdx5dmipjlxfP5M3YL4QCJoySB+sY92de5b3S3tqmj7ldb/GRvN/7XjoMDwbRso6
jrhGtk8TjtAV0l/VdjebpI6zivrDLYDQq5vwi6hGPl7k88ElU47vaJiJX5yXaJ/k
LFQ3g8raFQq69nqcDjJLGds+Y+lAXrtzuQENBFsQEBkBCAC9ZUHiXbBLvCejMXKK
vFpKaVsovI6RBU8l0sC+00yvpP+TJmRXracnesTqHyTlhAUMhpbFvG0mBMBdROt5
IPRZ2S9JdJKZFVqO7Nop0elO8wUe6rsEHisUbEP49BcqDHGxfEnB/MubnJO1hHEH
1ftnZBEQW3jNagOTikki9675qF4ONvaSeCY9DkHa4lbau24SzePvtWuxYGsdX+Jf
ikFxq8N2ArPlSoVv/DKEbl5dgz1hYFJ9qBKoXSbaKk1TxZ4bA8nxcznZHS+8Lirv
tEjB8Z68Hz+pXIFJBbchC/FMatZC2hjFobedc4dT3nxf5iiH9XsHI5bqp3UEsPlx
8LP5ABEBAAGJATYEGAEIACACGwwWIQRjr3qhUGfAVhb93YijoujyJvC8BgUCWxAR
IQAKCRCjoujyJvC8BhGMCACkNhkshrOYDRoOwny8m1mI2nSIU0KnjEruaeAXrY2T
5VHNfLkTX3wD2HYO97r1CvUNBUWpmTwSicK0Z6TCDp4A9Oi+z5CA/5zBT/iydC6E
czNAPUehdLKka9Qs0vrVq22S0dDiA4xXZUvQpoo8VUKlvau9igF98mbd56U89s3L
gg7O72A/4x7rhDO0Q+U8SIBJtFmEHIcu6gHkooQW3d7opHKCjbnyqxDQ/iUY3b8o
n75TXnDJWbjCFTiTMyVTeyQfK0Us8FbJNXhMMagalRQu/sBH56S7Cg2OLciQB1B2
sLbhbfYDXYriI/OGVIPvCEIH6FX4+KiFy7RS+0JthI0R
=fQDM
-----END PGP PUBLIC KEY BLOCK-----

You can find the above current (as well as the old) key in the README.md file of the wp-cli/builds repository, as well as in the form of a downloadable file in that same repository: wp-cli/builds/wp-cli.pgp.

The new key is configured to be the following user:

WP-CLI Releases (releases@wp-cli.org)

The new key will not expire.

In case you have problems with using this key, please open an issue in wp-cli/wp-cli.

#gpg, #key, #release, #signing

Version 1.5.1 released

A new release is upon us!

We’re excited to bring you WP-CLI v1.5.1, an intermediary bugfix release with a total of 52 merged pull requests since v1.5.0 in January 2018.

About this release

This is a bugfix release, which means that you shouldn’t expect major feature enhancements. We’re working hard on v2.0.0 which is planned for the summer, and all new features will have to wait for that big one.

Notable features

Yes, I just said not to expect any new features. However, a small number of features managed to sneak into this release nevertheless.

Edit your config files with ease

The config command now has a new config edit function that opens the wp-config.php file in your favorite editor for easy changes. You can configure the editor to be used through the EDITOR environment variable [#48].

Get better insight into your capabilities

Although WordPress is able to have a capability be set to false, to effectively mean an explicit  “deny” of that capability, WP-CLI did not yet show that distinction. It only let you know that the capability was defined, but not whether it was negated, giving the false impression of it being “allowed” instead.

This has now changed, and you can get a complete picture of how the capabilities are set by adding the --show-grant to the cap list command [#19].

Breaking change: Note that the default behavior of cap list has slightly changed because of that. Whereas the previous version showed a capability set to false alongside the normal capabilities, a simple cap list without the new --show-grant flag will now hide the capabilities that are set to false, effectively returning only the capabilities that are actually “granted”.

Bugs that were fixed

Framework

  • Show help text even when proc_(open|close) aren’t available [#4758]
  • Normalize Mac tar output [#4674]
  • Tests should not depend on external commands [#4673]
  • Fix phpunit extractor, glob, behat tests [#4672]
  • Move phpunit PHP directive tests to behat [#4675]
  • Only run phpcs against PHP files on pre-commit hook [#4755]

Commands

  • plugin verify-checksums
    • Make soft change detection more flexible [#41]
    • Add backslash to the regex for matching Windows paths correctly [#39]
  • config
  • package
    • Assume default package name if composer.json file cannot be retrieved [#78]
    • Avoid using Composer CA bundle if in phar [#72]
  • scaffold block
    • Fix theme-specific paths in scaffolded blocks [#137]
    • Modify scaffold block to create index.js [#142]
  • scaffold plugin
    • Exclude tests/test-sample.php via the phpunit.xml.dist file [#134]
  • scaffold plugin-tests | theme-tests
    • Fix WPCS in theme-tests generation [#121]
    • Use correct default $WP_TESTS_DIR on MacOS [#131]
    • Fix sed -i option on MacOS [#132]
    • Switch CircleCI template to CircleCI 2.0 [#115]
    • Add PHP 7.2 to CI templates [#135]
  • search-replace
    • Handle incomplete class (un)serialization gracefully [#76]
    • Handle PCRE errors gracefully [#75]
    • Remove “Site Not Found” message from multisite usage [#69]

Contributors to this release (15 total)

danielbachhuber, emirpprime, ericgopak, felicianotech, gitlost, johnbillion, kshaner, lalaithan, pdaalder, ptrkcsk, salcode, schlessera, stevegrunwell, thrijith, torounit

#release, #v1-5-1

Upcoming bug-fix release 1.5.1

We’re planning a bug-fix release v1.5.1 that is scheduled for Friday, 20th April, 2018.

Here’s the list of bugs we’re planning to fix for this upcoming release:

Given the tight deadline, this list is quite ambitious, and we’d love to have some additional help to make this happen. We’re glad about any contributions (code or otherwise) to help us fix up this list as completely as possible.

UPDATE: You can follow the progression here: https://github.com/wp-cli/wp-cli/issues/4766

#v1-5-1

Version 1.5.0 released

It’s release day again!

We’re excited to bring you WP-CLI v1.5.0, with a total of 279 merged pull requests since v1.4.1 in November 2017.

This release was led by the tireless Martin Burke (@gitlost), who made sure no bug went unsquashed and no edge case untested.

New committer

  • Pascal (@swissspidy) lives in Zurich, Switzerland. Amongst other contributions, he’s been doing the hard work on the embed family of commands.

Plugin checksum verification

WP-CLI can now verify the integrity of your installed plugins through the new plugin verify-checksums command (in addition to the already existing core verify-checksums command). [#15], [#26]

# Verify the files of all installed plugins against their official checksums.
$ wp plugin verify-checksums --all
+-------------+---------------+-------------------------+
| plugin_name | file          | message                 |
+-------------+---------------+-------------------------+
| gutenberg   | backdoor.php  | File was added          |
| gutenberg   | gutenberg.php | Checksum does not match |
+-------------+---------------+-------------------------+
Error: Only verified 1 of 2 plugins (1 failed).

Note: This is a first iteration on this functionality, and it still comes with a few limitations:

  • It only works for plugins that are hosted in the official plugin repository.
  • It only works for recent versions of these plugins, as we haven’t yet rolled out code on the wordpress.org backend to retroactively generate the checksums for older versions.

Please keep these limitations in mind when you plan on using this new command.

As we will further iterate on this project to allow verification of all free themes from the themes repository, and later hopefully also third-party plugins/themes, we welcome any and all feedback to the current implementation.

WordPress config file manipulations

Managing your wp-config.php file just got a whole lot easier! Not only did we improve the config get and included both a config has and a filterable config list command… No, we finally bring you full WordPress Config file manipulation with the new config set and config delete commands. [#42], [#44]

# Get the table_prefix as defined in wp-config.php file.
$ wp config get table_prefix
wp_

# Check whether the DB_PASSWORD constant exists in the wp-config.php file.
$ wp config has DB_PASSWORD
(return exit code)

# List only database user and password from wp-config.php file.
$ wp config list DB_USER DB_PASSWORD --strict
+-------------+-------+----------+
| key         | value | type     |
+-------------+-------+----------+
| DB_USER     | root  | constant |
| DB_PASSWORD | root  | constant |
+-------------+-------+----------+

Big thanks to @fjarrett for the awesome work on the wp-cli/wp-config-transformer package that powers the changes to wp-config.php.

oEmbed management

The new embed command allows you to inspect and manipulate the oEmbed object, for instance you can clear the cached values for a particular post with

$ wp embed cache clear 123
Success: Cleared oEmbed cache.

or reset the cached values with

$ wp embed cache trigger 123
Success: Caching triggered!

You can find out what the embed HTML is for a URL with fetch:

$ wp embed fetch https://www.youtube.com/watch?v=dQw4w9WgXcQ
[youtube https://www.youtube.com/watch?v=dQw4w9WgXcQ?feature=oembed&w=525&h=295]

or look at exactly what the provider is returning by using the --raw option:

$ wp embed fetch https://www.youtube.com/watch?v=dQw4w9WgXcQ --raw
{"height":295,"thumbnail_height":360,"provider_name":"YouTube","provider_url":"https:\/\/www.youtube.com\/","author_name":"RickAstleyVEVO","width":525,"version":"1.0","thumbnail_width":480,"author_url":"https:\/\/www.youtube.com\/user\/RickAstleyVEVO","html":"<iframe width=\"525\" height=\"295\" src=\"https:\/\/www.youtube.com\/embed\/dQw4w9WgXcQ?feature=oembed\" frameborder=\"0\" allow=\"autoplay; encrypted-media\" allowfullscreen><\/iframe>","title":"Rick Astley - Never Gonna Give You Up","thumbnail_url":"https:\/\/i.ytimg.com\/vi\/dQw4w9WgXcQ\/hqdefault.jpg","type":"video"}

And lots more!

Array argument support (post meta for now)

The --meta_input option of the post create and post update commands now accepts JSON-formatted arrays, so you can add or update your post and its meta in one go:

$ wp post create --post_title='Title' --post_content='Content.' --meta_input='{"key1":"value1","key2":"value2"}
Success: Created post 123.

A great time saver, as you’d previously have to run three separate commands to get the same result.

This rather innocuous change means we can finally accept associative arrays as parameter arguments, through the use of this JSON syntax. The --meta_input parameter is probably just the first of many more to come. Let us know if you can think of other potential use cases for this syntax.

Everything else in v1.5.0

Backward Compatibility breaks

Please note that a framework change [#4624] alters the behavior of table filter arguments to the db search, db tables and search-replace commands.

The table filter arguments now:

  • Respect registered wpdb tables when given a table filter and not given the --all-tables-with-prefix or the --all-tables option.
  • Do not ignore the --scope option when given the --network option.
  • Tables are always returned in sorted order.

Also note that option list no longer shows transients by default [#127].

New and notable

  • user reset-password: Resets a user’s password [#119].
  • Command descriptions now follow the WordPress norm and use the third person singular, thanks DrewAPicture !

Command improvements

  • cli info:
    • Displays OS & shell information [#4604], [#4610].
  • core download:
    • Skips cache also when ZIP URL is 'http://' to nightly build [#44].
  • core update:
    • Ignores SSL trigger_error in WP get_core_checksums() [#48].
    • Strips wp-content/ using ZipArchive to always allow --skip-content [#59].
  • core verify-checksums
    • Warns when files prefixed with wp- are included in WordPress root [#28].
  • db *:
    • Uses new after_wp_config_load hook for early invocation of db commands [#57].
  • db check/cli/create/drop/export/import/optimize/query/repair/reset:
    • Adds --dbuser and --dbpass options to all the heightened privilege commands, and extra arguments option to check, optimize and repair [#75].
  • db search:
    • NOTE: See Backward Compatibility breaks above on treatment of table filter arguments [#4624].
  • db size:
    • Ensures default value of --size_format=<format> argument is always bytes [#69].
    • Includes support for TB and GB database size formats [#81].
  • db tables:
    • NOTE: See Backward Compatibility breaks above on treatment of table filter arguments [#4624].
  • export:
    • Adds --with_attachments option to force including attachments when --post__in has been specified. [#16].
  • media image-size:
    • Adds size ratio to output [#58], [#59].
  • media regenerate:
    • Does not throw PHP warning if no sizes metadata [#61].
  • option get:
    • Display error message if option doesn’t exist [#126].
  • option list:
    • Defaults to not showing transients [#127].
  • package *:
    • Caters for mixed-case package names [#49], [#50].
    • Adds GITHUB_TOKEN and COMPOSER_AUTH handling [#47].
  • package browse/list:
    • Catches exception if browsing/listing packages and Composer can’t access a repository [#60].
  • package install/uninstall:
    • Reverts composer.json on memory limit error [#64].
  • package install:
    • Retrieves package name from correct branch [#65].
  • plugin install:
    • Uses the Github project name as the plugin directory for Github archive URLs [#81]
  • post create/update:
    • Adds the ability to add multiple metadata by passing JSON-formatted arrays to --meta_input [#133], [#138].
  • post create:
    • Accepts category slugs in --post_category and checks if incorrect ids or slugs given [#129].
  • post delete:
    • Corrects delete message [#124].
  • post generate:
    • Adds support for generating a specific post_title [#94].
  • scaffold block:
    • Scaffolds a basic Gutenberg block for a plugin or theme [#96].
    • Adds inline documentation based on the Gutenberg Handbook, generates style.css, supports latest supportsHtml API, WordPress Coding Standards fixes [#107].
    • Updates PHP template to latest recommended method [#111].
  • scaffold child-theme:
    • Generates WordPress Coding Standards compliant code [#117].
  • scaffold plugin:
    • Adds a default task to scaffolded Gruntfile.js [#87].
    • Generates WordPress Coding Standards compliant code [#120].
  • scaffold plugin-tests:
    • Uses Composer to determine which PHPUnit version to install, instead of keying off Travis environment variable [#75].
    • Adds XML declaration to phpunit.xml.dist [#78].
    • Uses updated error message in bootstrap.php [#90].
    • Removes Composer vendor directory from Travis CI cache [#99].
  • scaffold post-type:
    • Trims dashicon- from dashicon argument to prevent duplicated string [#70].
    • Refreshes scaffolded post type labels [#84].
    • Generates WordPress Coding Standards compliant code [#110].
  • scaffold taxonomy:
    • Adds term_updated_messages to scaffolded taxonomies [#82].
    • Generates WordPress Coding Standards compliant code [#112].
  • scaffold theme-tests:
    • Adds theme_root filter to tests/bootstrap.php to make sure theme’s functions.php gets loaded [#116].
  • search-replace:
    • NOTE: See Backward Compatibility breaks above on treatment of table filter arguments [#4624].
    • Adds --skip-tables=<tables> argument to exclude specific tables [#48].
    • Disables report tables without index when using --report-change-only [#54].
    • General improvements to reporting, including disabling table display when no tables to output [#57].
    • Fixes not quoting non-integer primary keys [#59], [#63].
  • user remove-caps:
    • Errors if the cap doesn’t exist or is inherited from a role [#125].

Framework enhancements

  • Improves warning when can’t create cache directory [#4456].
  • Allows method @when to override class @when [#4458].
  • Pulls links from help texts into footnotes [#4465].
  • Implements command namespaces [#4470].
  • Generates get_site_url() without set_url_scheme() [#4473].
  • Introduces new after_wp_config_load hook (used to invoke wp db * early) [#4488].
  • Gets the hostname automatically with vagrant ssh-config [#4495].
  • Indicates other WP installs in db when install isn’t found [#4476].
  • Permits use of php7.1-mysql in Debian build [#4511].
  • Supports 'longdesc' as command argument when registering a command [#4513], [#4636].
  • Improves Extractor error messages [#4510].
  • Runs wp cache flush and wp search-replace on multisite even when site isn’t found [#4527].
  • Fixes prompting on Windows git/cygwin bash [#4547].
  • Doesn’t show 'sitecategories' table unless global terms are enabled [#4552].
  • Ensures late-registered registered commands appear in usage [#4564].
  • Improves Windows compatibility on invoking a proc and using more.com [#4572], [#4595].
  • Uses a softer PHP requirement in RPM build [#4571].
  • Only provides dictionary-based suggestions if they produce valid options [#4590].
  • Adds interval argument to make_progress_bar() [#4603].
  • Adds Utils\esc_like() polyfill of wpdb version [#4612].
  • Deals correctly with wildcards in wp_get_table_names() (see Backward Compatibility breaks above) [#4624].
  • Adds shell array parsing helper [#4623], [#4635].
  • Checks for readability of WordPress core files [#4626].
  • Adds some more suggestions for mistyped arguments [#4577].

Contributors to this release (39 total)
ahmadawais, BhargavBhandari90, danielbachhuber, davidbhayes, DrewAPicture, drzrafecotechie, emgk, eriktorsner, fjarrett, gitlost, grantpalin, gziolo, inetbiz, kirtangajjar, LC43, lukecav, marcochiesi, marksabbath, miya0001, mm-pagely, neonardo1, ntwb, ocean90, playmonorkialashaki, runofthemill, ryotsun, sagarprajapati, schlessera, Shelob9, ssnepenthe, swissspidy, szepeviktor, terriann, thrijith, vbaranovskiy-plesk, vigilanteweb, websupporter

#cli, #release, #v1-5-0

Minor programming notes

Quick announcement before things totally shut down for the holidays:

  • Martin Burke (@gitlost) will be taking the Release Lead role for WP-CLI v1.5.0, due out on January 30th. He’ll be making sure all of the i’s are dotted and t’s are crossed before the version is tagged and deployed.
  • Alain will continue on as maintainer in a supporting role to Martin, helping out on a day to day basis with triaging the deluge of issues and pull requests.
  • I (Daniel) will be stepping away from day to day maintenance of WP-CLI, but will be around to support Martin and Alain as needed.

But why? Is this the end of the world?

My goal is, and always has been, long-term stability and quality for WP-CLI. I want WP-CLI to be software you can depend on for years, not months.

Part of longevity is consistent baseline investment into maintenance, with occasional bursts of new feature development. But longevity is also the human capacity around the project, of which I cannot be the bus factor. Stepping away creates space for others to step up.

Martin and Alain are very intelligent individuals. I trust they’ll do a great job.

Are you planning to come back?

We’re trialing this through the release of v1.5.0, and will reassess after that point.

I’m personally looking forward to: 1) taking a true mental break (my first WP-CLI PR was September 2012), and 2) submitting pull requests to WP-CLI as a contributor again.


If you’ve been hesitant to contribute to WP-CLI, now’s your time to dive in and help out. I’m sure Martin and Alain would love your enthusiasm 🙂

Live long and prosper!

Call for action – Help us test Checksum Verification

We’ve been working on building a first usable implementation of the plugin checksum verification project. Now we need your help to test the current implementation.

Implementation Details

The WordPress.org infrastructure now calculates MD5 and SHA-256 checksums for all plugin files and stores them in a publically accessible way. You can find a specification of the current endpoint to retrieve the checksums here.

The wp checksum plugin command we’ve built goes through some or all of the plugins installed on a machine, downloads the checksums for each plugin, and then verifies the downloaded checksums against freshly generated ones.

We now need help testing this command to make sure we weed out all edge cases and that its output serves all expected scripting requirements.

Right now, the output on STDOUT will provide you with a list of checksum mismatches or added/removed files. STDERR will contain warnings about skipped plugins. The exit code will return 0 if all compared checksums were valid, and 1 otherwise. Any feedback on whether that is a good approach, or on alternative approaches for the output are welcome!

Let us know as well when a plugin’s checksums is not found that you would expect to be found in the official plugin repository. Note: Right now, only the checksums for the latest versions of every plugin have been calculated, older versions will be added later.

How To Test

The implemented command can be found in the plugin-checksums branch of the wp-cli/checksum-command repository.

You can easily install the version to test through the following command:

wp package install wp-cli/checksum-command:dev-plugin-checksums

To get back to the stable bundled command later on, just type the following command:

wp package uninstall wp-cli/checksum-command

The easiest way to run the test is to enter the root folder of an existing WordPress site and run the following command:

wp checksum plugin --all

The command supports several formats, like JSON or CSV, which you can generate through the --format=<format> parameter.

Note: the output will be most useful right now if all plugins are up-to-date (as older checksums have not been calculated yet), so you might want to run a wp plugin update --all against local sites you test. Obviously, don’t do this without backups on production sites.

Please report any feedback or issues you find in the GitHub issue tracker of the checksum command.

Timing for v1.5.0 and v2.0.0

A heads up on some upcoming scheduled changes:

  • WP-CLI v1.5.0 is slated to be released on Tuesday, January 30th. This will be the last release in the v1.x series, unless some critical issue necessitates a v1.5.1.
  • WP-CLI v2.x will require PHP 5.4 and higher. Given current release cadence, v2.0.0 could be released in the May timeframe.

Why? Travis CI is ending support of PHP 5.3 testing (targeting early April). I’m not very keen to invest time into some alternate CI system solely for those still running PHP 5.3.

If you manage WordPress installs for others and don’t already have systems for helping them safely update PHP, you should take the time in 2018 to develop said systems.

Good issues for new and existing contributors

Want to submit your first pull request to WP-CLI? We’ve identified a few good first issues for you to get your feet wet:

If you’ve contributed to WP-CLI before, here are some reasonably well-defined issues we’d like to see pull requests for:

Read through the contributing guide for details on how to get started. Feel free to ask questions on the specific issue, or join us in the #cli channel with any questions you might have.