Free WP-CLI stickers for your event!

Want to share your love of WP-CLI with your community?

Starting today, you can fill out this form to request stickers (free of charge) to distribute at your WP-CLI-related event (WordCamp, meetup, or otherwise).

Some fine print to be aware of:

  • Requests must be made at least four weeks in advance of the event by an official organizer of the event.
  • Offer is for up to 50 stickers to any geographic region Stickermule can ship to.
  • Stickers must be made available in a public common area and announced at the beginning or end of the WP-CLI session.

Feel free to reach out to danielbachhuber on Slack with any questions. Happy scripting!

X-post: Community Conduct Project – Kick off meeting scheduled for 17:00 UTC on the 5th September 2017

X-comment from +make.wordpress.org/updates: Comment on Community Conduct Project – Kick off meeting scheduled for 17:00 UTC on the 5th September 2017

Version 1.3.0 released

Happy release day! After 210 total merged pull requests, we’re excited to bring you WP-CLI v1.3.0.

Install packages with shortened identifiers

Recently, we have been discussing the future of the WP-CLI package index. Our conclusion was to deprecate the existing package index for now and provide a new mechanism for more easily installing external commands that are hosted on GitHub.

As of WP-CLI v1.3.0, whenever you provide a package identifier in the form of <vendor>/<package>, WP-CLI will first check the deprecated package index (for backward compatibility reasons), and then check for a GitHub repository that matches this identifier. This also accepts all version qualifiers/requirements that Composer can parse.

Examples:

# Install vendor/command from GitHub (uses https://github.com/vendor/command):
$ wp package install vendor/command

# Install version 1.0.5 of vendor/command:
$ wp package install vendor/command:v1.0.5

# Install commit 95ce52b of vendor/command:
$ wp package install vendor/command:dev-master#95ce52b

New commands

Wondering whether a specific string exists in your database? Wonder no more! Use the new wp db search to search through all text columns in your database for your specified string (or regex pattern) [#29, #33]:

# Search through the database for the 'http://' regular expression, printing stats.
$ wp db search 'http:\/\/' --regex --stats
wp_comments:comment_author_url
1:https://wordpress.org/
    ...
Success: Found 99146 matches in 10.752s (10.559s searching). Searched 12 tables, 53 columns, 1358907 rows. 1 table skipped:
wp_term_relationships.

Need easy access to the database prefix for chaining into other commands? Use wp db prefix to print it out [#22]:

$ wp db prefix --url=example.com/foo
wp_3_

Everything else in v1.3.0

Command improvements

  • wp config *:
    • Errors early when no wp-config.php can be found [#22].
  • wp config create:
    • Generates keys/salts locally and use WordPress.org API as fallback [#25].
  • wp config get:
    • Adds --constant=<constant> or --global=<global> to get the value of a specific constant or global [#16].
    • Indicates files included by wp-config.php [#18].
  • wp core (multisite-install|multisite-convert):
    • Use --skip-config to avoid addition of multisite constants to wp-config.php file [#18].
  • wp import:
    • Prevents non-existent directories from ending up in the list of files to import [#8].
  • wp media *:
    • Changes media noun to ‘items’ in most cases, to reflect multi-type nature of media [#18].
  • wp media import:
    • Adds --skip-copy flag to allow import of media from local filesystem without moving on disk [#21].
  • wp package install:
    • Adds support for short package identifiers [#22].
  • wp post term delete:
    • Implements --all flag to remove all terms from a post [#23].
  • wp scaffold *:
    • Creates phpcs.xml.dist instead of custom-named phpcs.ruleset.xml [#19].
    • Better support for symbolic links [#26].
    • Changes the grunt config for addtextdomain to override all text domains by default [#28].
  • wp search-replace:
    • Includes --format=count to only show number of rows affected [#14].
  • wp term (get|update|delete):
    • Introduces --by=<type> argument to get/update/delete term by slug [#27].
  • wp user *:
    • Support fetching users with an email address in the login field [#21].
  • wp super-admin remove:
    • Allows revoking super-admin of non-existent user [#6].

Framework enhancements

  • Fixes autoload file names for $custom_vendor condition [#4147].
  • Saves runtime config so it can be passed as args to Runner::run_alias_group() invocation [#4148].
  • Manually loads comments if opcache.save_comments is disabled [#4161].
  • Allows numbers in subcommand names and arguments [#4164, #4269].
  • Fixes double slash in boot-phar.php path [#4169].
  • Allows root use of wp cli info, in addition to wp cli update [#4177].
  • Updates SSH URL parser regexp to allow for null port number [#4182].
  • Add WP_CLI\Utils\get_home_dir() helper function [#4184].
  • Reduces included files (Behat/PHPUnit in particular) in built Phar [#4185].
  • Behat: Allows test DB user + pass to be set by environment variables [#4196].
  • Fixes output in JSON format in case of error while encoding [#4199].
  • Passes WP_CLI_STRICT_ARGS_MODE on to --ssh=<ssh> if set [#4207].
  • Displays a more helpful error message when site cannot be found [#4212].
  • Fixes broken indentation on Windows systems because of line endings [#4221, #4222].
  • Adapts --ssh=<ssh> flag to work with Docker and Docker Compose [#4240].
  • Checks for availability of proc_open/close in various scenarios [#4245].

Contributors to this release (45 total): aaemnnosttv, BhargavBhandari90, chetansatasiya, chriszarate, cjhaas, colemanedwards, danielbachhuber, davetha, drrobotnik, electrokit, emgk, emirpprime, erikjoling, fjarrett, freegenie, gitlost, greatislander, iansvo, Ippey, jalavoy, jameselks, joehoyle, johnbillion, @JPry, junaidbhura, kouratoras, lucatume, @mapk, mikeschinkel, miya0001, @murtzsarialtun, nikolov-tmw, pierre-dargham, plastikdreams, rahul286, ronaksampat, schlessera, Sidsector9, soulseekah, szepeviktor, tfrommen, vbaranovskiy-plesk, westonruter, wp-make-coffee, wpbullet

Good first issues for new contributors

WP-CLI v1.3.0 is coming soon!

Want to submit your first pull request to WP-CLI? We’ve identified a few good first issues we’d love to get in the next release:

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

Community Summit: Contributing to WP-CLI

“Contributing to WP-CLI” was the second of two discussions we held at the Community Summit. For notes from the first, see details embedded in the feature development post.

We began the conversation by giving an overview to the current contribution process. Notably:

From the introduction, the conversation turned more free-form. In no particular order, some highlights:

  • One big challenge is that WP-CLI is a rather complex project and assumes a lot of knowledge from a contributor. When onboarding new contributors, they have to learn two things: the process for contributing, and how everything works (without reading the code). Although the internals page is reasonably helpful, it doesn’t cover the command execution flow. Having a flow document would be useful.
  • One observation is that potential contributors can enter the project in different ways (e.g. GitHub repo for a custom command vs. a third-party tutorial on how to use WP-CLI). Documentation primarily provides a linear path.
  • We’re seeing some contributors submit documentation but not a ton. It’s unclear whether this indicates the documentation is good enough, or whether the path to contributing documentation is too confusing. It’d be helpful to see more users open questions about the documentation, as a way of validating/improving the content.
  • Another challenge is that generally of WP-CLI tools is that the user knows the abstract problem, but not which command addresses the problem. Related to this:
    • It would be useful if a help command also included the URL for more information.
    • It’d be nice if you could easily see a tree of all commands.

Thanks to everyone who participated!

Feature Development Discussion Recap

This week’s WP-CLI office hours had been a special “feature development and the package index” edition, as was announced in the previous post: How should we embark upon new feature development?

Here’s a link to the chat log. The attendees were: @danielbachhuber, @dave_navarro, @grapplerulrich, @miyauchi, @modernnerd, @nerrad, @schlessera.

Chat summary:

We started with a quick recap of what the different approaches were that we already presented in the previous post:

  1. No package index, but community-driven feature development
  2. Submission proposal that is coupled to precise quality and maintenance requirements
  3. Two-tiered system with both an “official” index and a “community” index

Most of the discussion that immediately followed revolved around approach C, and what the best technical implementation of such a system would be.

It is clear that this involves a lot of work on the infrastructure that supports these different tiers. Some existing package indexes/managers were mentioned as a comparison: npm/packagist in terms of being a similar CLI tool, but also rpm as a package system that allows arbitrary repositories to be added as a package source.

When I told the group that we were considering going with approach A for now, while targeting some form of C as a longer-term goal, people seemed to agree in principle. The discussion that followed then made it rather clear that we are discussing two distinct problems and trying to find a solution for both at the same time:

  1. A mechanism to install external packages that allows to differentiate between “official” and “third-party” packages.
  2. A mechanism for discovery of new packages, that allows searching and/or browsing some type of collected index.

This lead the group to reason about these two problems separately, and ultimately allowed us to formulate the following plan:

  • For installing packages, we won’t have an actual “index” in place, we accept any Composer source (git repository, zip file, path to folder, …) as a package, with the added detail that a package identifier of vendor/package will default to the corresponding GitHub repository.
  • This makes it obvious what an “official” package is: any package under the wp-cli GitHub organization.
  • This also allows all third-party packages that are hosted on GitHub to be easily installed via such a shortened package identifier, without the need to add them to any sort of index.
  • In case this is needed, we will provide a backward compatibility mapping to make sure the packages from the current package index still work as expected.
  • The current package index will be retired. It will not be deleted, though, to keep legacy versions of WP-CLI working as expected.
  • “Discovery” is then an entirely different problem and will be solved through a separate (potentially third-party) project.

We will now start work on investigating this specific approach. Expect several issues to pop up on GitHub related to this.

This also means that the actual feature development will now be handled as was described for approach A. Ideas are collected within the wp-cli/ideas repository. The ones that get the most traction get included in the roadmap to build as new official packages, which means they will be part of the wp-cli GitHub organization. We will more clearly define our policies surrounding this process and include them in the contributor’s documentation.

We are still very grateful about any feedback we can get about this important aspect of WP-CLI, so don’t hesitate to share your thoughts in the comments below!

How should we embark upon new feature development?

Update July 11th:  We’re having a follow-up discussion in Slack (#cli channel) next Tuesday, July 18th at 16:00 UTC (9 am PT, 12 pm ET). Our goal is to get to the point where we have a rough sense of the path forward.

The WP-CLI package index is a directory of user-maintained commands. For a long while now, submissions have been put on hold. I’d like to unblock new feature development, but we first need to address the conundrum before us.

Originally, the package index was created as space for developers to share custom WP-CLI commands. A developer would write a new command, submit it to the index, and the command would be displayed on the website for others to discover. The command would also become installable through wp package install.

However, the package index suffered from the same problems that plague the WordPress plugin directory:

  • After a while, submitted packages are no longer actively maintained. Eventually, they become abandoned. Maintaining packages is commonly a solo-author activity when it needs to be a multi-author activity to be sustainable.
  • Over time, different implementations are submitted of the same feature. I actually ended up pausing acceptance of new packages when four of five submissions were near duplicates of existing packages.

Just like WordPress, the end-user experience is the priority for the WP-CLI project. It’s a bad user experience to have to choose from multiple poorly-maintained implementations of the same feature. It’s a much better user experience to have one high-quality, well-documented solution to a specific problem.

Not only that, but we’d much rather focus contributor effort towards maintaining common packages, rather than have spread amongst a number of one-off individual implementations. The maintenance burden of the command ecosystem is much easier to manage when somewhat centralized, than spread amongst numerous small projects.

Given what we know at the moment, our priorities are the following:

  • Provide an outstanding user experience.
  • Have a streamlined pipeline for adding needed functionality.
  • Be able to maintain and adopt packages to keep them available for the community.
  • Keep maintenance effort in check.
  • Encourage contributions in many forms.

What we want to avoid is any of the following:

  • Outdated / abandoned packages being endorsed to users.
  • Duplicated functionality causing confusion.
  • Maintainers being a bottleneck.

We were fortunate enough to be able to discuss this problem during the WordPress Community Summit. Brainstorming with other community members, we were able to identify three possible approaches so far:

A. No package index, but community-driven feature development.

Ideas are collected within the wp-cli/ideas repository or a similar tool. The ones that get the most traction or votes get included in the roadmap to build as new official packages.

Observations from the discussion:

  • Solves problems noted above by having WP-CLI be the sole source of endorsed packages.
  • Not practically feasible in terms of team effort.
  • Too slow to make progress and act on requirements.

B. Submission proposal that is coupled to precise quality and maintenance requirements.

To get included in the package index, you need not only ensure high quality but also commit to regular maintenance.

Observations from the discussion:

  • Adds strict procedures and requirements to the current package index.
  • Could include the provision that abandoning a package will cause it to be adopted by the WP-CLI project itself.
  • Growing team effort that will become problematic over time.

C. Two-tiered system with both an “official” index and a “community” index.

The “official” index is controlled and endorsed by the WP-CLI team, while the free-for-all “community” index will include a notice that use of these packages is at everyone’s own risk.

Observations from the discussion:

  • Completely open directory is valuable for innovation.
  • Submissions could default to the “community” index, and packages then need to submit a proposal to get “promoted” to the “official” one if they meet the requirements.
  • Adds cognitive overhead by having two sources of packages, with potentially two different mechanisms of installation.

None of these three approaches is a perfect fit for our priorities above, they just provide differing sets of benefits and drawbacks. In addition, we are quite sure there are other models out there that can potentially be adapted to meet our needs.

This is where we are hoping for valuable input from the community. There are some specific decisions we need to make:

  • What process should we follow for new feature development?
  • Is it possible to adapt the existing package index to help us achieve our priorities?
  • If yes, what form should it take?
  • If no, is there another mechanism might we employ?
  • What should we do with the pending submitted packages?

Have some perspective to share or process to suggest? Know of other projects that we can model our approach on? We’d appreciate your comment on this post, especially if it also includes pros, cons, expected maintenance burden effort, etc.

Please keep in mind that we may make a decision you don’t agree with. Our decision will be biased to reflect the priorities of the project.

We greatly welcome your input to the decision-making process, though, particularly to the degree that it’s respectful, introduces perspective we may not have considered, and represents a great deal of thought and consideration.

#cli

Good first issues for new 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:

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

WordCamp Europe 2017 Contributor Day Recap

On Thursday, June 15th, WordCamp Europe 2017 in Paris had the very first Contributor Day where WP-CLI was officially represented as a separate team that people could contribute to.

On the official WordCampe Europe 2017 website, you can find the organization information that was sent to the attendees.

To get a sense of the event, you can visit the Contributor Day album by Olivier Gobet on Flicker.

Team Attendance

Over the course of the day, there were a dozen contributors joining the team to work on WP-CLI. Considering that the command line is not a mainstream topic in the WordPress world and that the team has only recently been officially added, we can consider this a success in itself.

After a small introductory round, it was clear that all of the contributors had prior experience with WP-CLI, either making regular use of it or even having already done development against it. This meant that we could skip the basic introduction and immediately dive into a more technical analysis of how the tool and its packages are architected.

We then split the team into two groups, depending on what the individual contributors preferred to work on: one group focussing on commands, and the other group focussing on the framework itself. The main difference between these two is the skill set needed: for the commands, the development closely mimics regular WordPress development, whereas for the framework, WordPress has not been loaded yet and the development is closer to pure PHP console development.

Things That Worked Well

Once we’ve split up the teams, we went through the Good First Issues page, and everyone was quickly able to find something to work on. This was a definite success, as I’ve often attended Contributor Days where some people were lost during the entire day, not really knowing where to focus their efforts on.

The fact that the code is managed through git and GitHub was well received by the contributors, as it made issue discovery easier and allowed for faster feedback cycles.

What made everything run smoothly as well was the fact that the contributors to join this team were mostly of above average technical proficiency. This meant that technical issues that were encountered were quickly taken care of, with people helping each other out, and there has even been an impromptu introductory session to test-driven development (TDD) by one of the contributors as well.

Things That Need To Be Improved

We are still facing some issues with the contributor onboarding process, mostly around documentation and testing.

One problem we faced was the fact that it is not obvious for most contributors that they need to create a test database first before being able to run the functional tests. Documentation could be clearer on this step, and we might even provide a hint in the console when the tests are being run without access to a database.

Another source of confusion was that there are different conventions (workflows, file names, …) of how to proceed depending on whether you want to work on a command, or the framework itself. This should all be streamlined so that every single wp-cli package will have the exact same requirements and support the same workflows.

Au Revoir

Big thanks to the organizing team of WordCamp Europe in Paris for the additional efforts they went through in order to find a space for our brand-new team! Although we hadn’t been included in the original planning (when they didn’t yet know about the WP-CLI team), we had a flawless experience and felt welcome as an integral part of the WordPress project.

Version 1.2.1 released

As it turns out, refactoring can introduce bugs. Who knew?!

WP-CLI v1.2.1 fixes a few regressions introduced in v1.2.0:

  • Properly registers commands to existing namespaces when defined by plugins [#4123, #4130].
  • Restores compatibility with using WP-CLI as a dependency of a Composer-based WordPress install [#4126].
  • Only forces use of /usr/bin/mysql on *nix systems [#4132].
  • Improves wordwrapping by using total columns in terminal, instead of an arbitrary width [#4133].

Want to help us catch these bugs earlier? Run wp cli update --nightly in your local and staging environments to use the latest and greatest.

Contributors to this release (4 total): danielbachhubergitlostschlesseraszepeviktor