Your help wanted: Gutenberg Migration Guide

This post originally appeared on make.wordpress/core.

Happy Thursday 🙂

I’ve started a new crowdsourcing project, the Gutenberg Migration Guide, to document WordPress Classic Editor customization points and their Gutenberg equivalents (if such exist).

For example, the media_buttons action is a common way to add a button atop the editor:

Its Gutenberg-equivalent is the Block Inserter. Converting a media button to the Block Inserter requires registering a block type. And now we have a corresponding page for developers to reference.

media_buttons is only one of the many ways the Classic Editor can be customized. Wouldn’t it be great if there was a database covering all of them?

This is where you come in! Take a look through the Gutenberg Migration Guide. For each action, filter, and so on, we’d like to document real-world examples of how they’ve been used. Then, for each of those real-world examples, identify how the feature might be replicated in Gutenberg.

Have a new hook to suggest or question to ask? Please open a new GitHub issue and we’ll get it sorted.

Introducing the Gutenberg Plugin Compatibility Database

This post originally appeared on

Ideally, the majority of WordPress users should be able to use Gutenberg on the day WordPress 5.0 is released. They'll hit "Update WordPress", navigate back to the editor, and continue publishing in Gutenberg with all of the functionality they expect in the Classic Editor.

But plugins! If any one of their active plugins are incompatible with Gutenberg, the WordPress user is likely to experience pain, misery, and bad fortune. Many WordPress installations have a dozen or more active plugins, so WordPress plugins are a significant risk vector for Gutenberg incompatibility.

Enter the Gutenberg Plugin Compatibility Database. The goal for this crowdsourcing tool is to identify whether or not plugins are compatible with Gutenberg. With this data set, we'll be able to:

  • Know the most likely causes of incompatibility.
  • Focus developer outreach on the highest impact problems.
  • Proactively educate WordPress users on whether or not their WordPress installation is ready for Gutenberg.

The only gotcha: we need lots and lots of person-hours for testing. If each plugin takes roughly 1 minute to test, we'll need ~75 person-hours to get through the remaining ~4500 plugins in the database.

Check out the project for a more complete introduction to what's involved. This includes a definition for "Gutenberg-compatible", explanation for why only 5000 plugins are in the database, and other design decisions.

Do you or someone you know have access to lots of person-hours (e.g. WordCamp contributor day, hosting support team, etc.)? I'd love to chat! Feel free to leave a comment, ping me on Slack (I'm 'danielbachhuber'), or get in touch however most convenient.

Brief plugin directory data analysis

While working on wordpress/gutenberg#4072 today, I was inspired to do some data analysis on the plugin directory.

To prepare, I populated a plugins table with data from the REST API via this plugin-stats.php script. Download the SQL file to avoid needing to re-fetch the API data.

Based on the initial API request, there are 49,749 total plugins.

Of the entire data set, only 18,002 plugins have 200 or greater active installs. The remaining 31,747 plugins represent an inconsequential number of active installs compared to the total.

The 18,002 plugins represent 182,296,500 total active installs. A WordPress install can have multiple active plugins, so this total isn't unique WordPress installs. Also, we can ignore the remaining ~32k plugins because they would only represent 3,174,700 additional active installs if each plugin had 100 active installs.

Of the total active installs, 168,623,000 (92.5%) are represented by 3,440 plugins with >=5000 active installs. For that matter, 159,720,000 (87.6%) are represented by 2101 plugins with >=10000 active installs.

It'd be interesting to know what percentage of WordPress installs have a plugin not tracked in the plugin directory (e.g. premium or custom).

Landing Gutenberg in WordPress 5.0

Some incomplete ideas I've been noodling on that I want to make public.

Ultimately, the goal is: the vast majority of WordPress users are excited and should be able to use Gutenberg on day one. Fundamentally, this breaks down into two objectives:

  1. Make the end-user experience is so good that WordPress users actively want to switch to it. We need to continue user testing as we have been, and iterate based on real user feedback. We also need to market Gutenberg — communicate what users should expect and get them appropriately excited.
  2. Mitigate WordPress plugin and theme incompatibilities, to minimize conflicts that would cause WordPress to fall back to the classic editor. Success is defined by the majority of WordPress users being able to use Gutenberg on day one. If too many can't use Gutenberg because of conflicts, then we've failed at launch.

I've been brainstorming some strategies for the latter, which really is two parts: identification and mitigation.

First, we need to identify the true extent of the problem: what plugins and themes are incompatible with Gutenberg, and in what ways are each incompatible? Some automated ways we can produce this data includes:

  • Manual/automated analysis of action and filters usage, etc.
  • Activate each in an isolated environment and take before/after screenshots of the editor screen.

But, I'm thinking good ol' fashioned crowd-sourcing might be most effective. What if WordPress users had an easy way to report whether a given plugin or theme was compatible with Gutenberg? We could collect this data in aggregate to get a good sense of what types of incompatibilities we should expect, and where we should focus our efforts.

Once we've identified the plugin and theme conflicts, we'll need to mitigate them. Doing so will require excellent documentation, so authors more easily understand the changes they'll need to make, and deputizing other developers to help with the outreach process.

WordPress plugin release checklist

Getting ready to release a WordPress plugin? Here’s a handy checklist you can follow.

1. Update the readme for the release

  • Include all changes in the changelog
    • List order is typically: major enhancement, minor enhancement, bug fix
    • Use active voice, present tense.
      • “Shows an admin notice when Redis is unavailable”
  • Update version numbers as appropriate
    • readme.txt
    • Plugin header in the main plugin file.
  • Compile from readme.txt (which is needed for
    • Run grunt readme.
    • Run grunt i18n.

2. Tag a new version on Github

  • Use the releases feature to create a new Release, with a Git tag of the appropriate version number (e.g. “v0.5.0”).
    • Double-check tag name / version number.
    • Copy and paste the changelog into the Release body.

3. Tag a new version on

  • Sync the codebase with plugin Subversion trunk
  • Create a new Subversion tag from trunk.
    • svn cp trunk tags/0.5.0
    • Commit the tag.

4. Publish blog post / execute promotion strategy as necessary.


New plugin: One Time Login

Need access to a WordPress install but don’t want to create a new user account? Use this plugin and WP-CLI to generate a one-time login URL for any existing user:

wp plugin install one-time-login --activate && wp user one-time-login <user>

After you run the command, you’ll see a success message like this:

Success: Your one-time login URL is:

Copy the URL, paste it into your web browser, and… voila!

Feel free to file issues and pull requests against the project on Github.

New plugin: Bitly URL Generator

If you need automatic Bitly integration with your WordPress, check out Bitly URL Generator, a rewrite of Micah Ernst’s classic plugin of the same name.

This version improves upon the original plugin in a couple key ways:

  • add_post_type_support( 'my-cpt', 'bitly' ) works as expected, without needing to register additional actions for your custom post type.
  • Introduces a wp bitly backfill WP-CLI command for generating Bitly short URLs on old posts, instead of doing the backfill with wp-cron.

Like the original, the plugin filters pre_get_shortlink to return your Bitly short URL for wp_get_shortlink().

Feature request, bug report, or violent dissent? Hit me up with a Github issue.

Tracking versions of WordPress plugins in theme directories

On WordPress projects where the entire application is defined by the theme, it can be common to submodule or directly commit WordPress plugins to a directory like theme-name/lib. However, in doing so, you lose out on WordPress’ built-in update tracking.

It would be cool to have a utility plugin that loads theme-specific plugins into the Manage Plugins view and WordPress update check.