Let’s do this!

As announced last week, WP-CLI is now an official WordPress.org project. I consider this the best possible outcome of my efforts trying to identify sustainability for the project over the last year. Frankly, it’s hard to communicate how relieved I am.

But wait, what does that actually mean?

Most of the details are still to be worked out. On a high-level, these are the big changes:

  • The website will be migrated to some part of wordpress.org, shape and form TBD.
  • Development will continue on Github, and could possibly move to github.com/wordpress/wp-cli (see below).
  • At the end of the day, I am no longer solely responsible for the project. If I were to be hit by a bus, there’s a more recognizable continuation plan for someone else to step in. Eventually, I hope to onboard a couple more maintainers who regularly invest significant time in the project.

The decision to make WP-CLI an official WordPress project also means there’s a clear path forward for me to invest more of my own time into the WP-CLI roadmap. Concurrent with the transition process over the next couple of months, I want to move forward the conversation of how we realize a future where WP-CLI is the fastest way to do anything with WordPress. If that’s something you’re interested in, stay tuned!

Migrating the website

In order to successfully and completely migrate the wp-cli.org website to wordpress.org (and WordPress), it’s important to understand its current form:

  • wp-cli.org is a Jekyll-based website hosted on Github / Github Pages.
  • Much of the reference documentation is generated by a series of WP-CLI commands from the WP-CLI codebase. These commands take structured data about the codebase and transform it into a series of Markdown files served by Jekyll. This documentation is typically regenerated for every major release.
  • The rest of the documentation is a series of user-editable files. It would be nice to be able to replicate the pull request workflow for editing the docs, because it’s a good source of contributions.
  • The WP-CLI package index (wp-cli.org/package-index) is built from a separate Github repository. It uses Satis to build the HTML and JSON representations of the package index. Satis is running on one of my personal servers.

These are the core functions needing to be replicated on WordPress.org. Ideally, the work done would be the foundation of where I’d love to see the WP-CLI website go in the future:

  • Produce command pages for the packages listed in the package index.
  • Proxy Github API requests for new WP-CLI versions (from 3426).
  • Display download / installation counts for each package.
  • Display number of Github stars for each package.
  • Highlight packages in the index that are regularly updated, have multiple maintainers, or reflect some other quality we hold to be important.
  • Create distribution releases for packages in the package index to speed up installation (from 2566).
  • Run test suite for each package on a weekly basis (from 3197).
  • Validate packages submitted to the package index (from 3177).

Migrating the Github repo

Fortunately, Github makes it easy to transfer repositories between organizations. Before we make the switch, we need to dot the i’s and cross the t’s on these core functions:

  • Travis is used to run the test suite. Travis also commits a build artifact to the builds repo.
  • WP-CLI’s update check uses the Github releases API. If Github doesn’t transform the request URI for migrated repos, then users will experience a cryptic error. Now that I write this, this dependency might be a large-ish problem.
  • Similarly, some users have build systems dependent on a consistent URL pattern for the release Phar file. See the releases page for examples.

It’s also worth noting there will be more WP-CLI repositories in the future. Each new feature will be developed as an independent package. In fact, existing features (e.g. search-replace) are going to be split out into separate packages too. We’ll need an organizational structure that can accommodate this growth (let it be github.com/wordpress/wp-search-replace-command or github.com/wp-cli-packages/search-replace-command).

Anything I’ve missed? Have a question about something I didn’t cover? Hit me up with a comment!

cc @pento