Posted on

Three flavors of Gutenberg backwards compatibility

This is my attempt at answering an issue I opened in January. Please take my opinions with a grain of salt.

WordPress is known for its commitment to backwards compatibility. It prides itself on functional consistency between major releases, and makes sure actions and filters continue to work as expected.

Gutenberg is big and huge and a significant change for the better. Contributors are working to make Gutenberg as backwards-compatible as possible. However, the reality is that we’ll likely taste three flavors:

  1. It continues to work as expected. For example, an enter_title_here filter continues to modify the title placeholder text in Gutenberg. Similarly, Post Type Supports is still the API for defining which features a Post Type supports.
  2. It doesn’t work but there’s an equivalent alternative. Some of WordPress’ existing architecture doesn’t translate directly into Gutenberg. For instance, media_buttons is the old paradigm for registering a button to insert something into the post content. In Gutenberg, Blocks are the new paradigm. Blocks are added to the post content via the Inserter.
  3. It doesn’t work at all. We want to avoid this as much as possible, but there will be some elements you can customize in the Classic Editor that you simply can’t change in Gutenberg.

The Gutenberg Migration Guide documents many of these specifics. New contributions are always welcome. Generally, compatibility solutions are organically prioritized against identified need, expected impact, and level of effort/possibility.

Ultimately, WordPress remains committed to the ethos of backwards compatibility, even when undertaking such a transformational change as Gutenberg. An amazing amount of effort is going into ensuring WordPress sites continue to work as expected. It’s important to acknowledge, though, that backwards compatibility is fundamentally more difficult than the past. The reality has a certain degree of nuance.

Posted on

Gutenberg nightly build

If you’d like to run Gutenberg’s master branch without creating your own build, you can use this plugin ZIP I’m building on a six hour cron:

https://builds.danielbachhuber.com/gutenberg-nightly.zip

Install the Gutenberg nightly build via WP-CLI with:

wp plugin install https://builds.danielbachhuber.com/gutenberg-nightly.zip --force

Once you’ve installed the Gutenberg nightly build, you’ll notice the version includes -alpha- followed by a seven character alphanumeric hash (e.g. 610aa4e).

This is an abbreviation of the Git hash at the time of the build. It’ll help you keep track as to whether you’re truly running the latest commit on master.

If you’d like to replicate elsewhere, here’s the underlying build script:

From WordPress/gutenberg#6285.

Posted on

Update on Try Gutenberg blockers

“Try Gutenberg” is an initiative, currently scheduled for WordPress 4.9.8, to drive more usage of the Gutenberg editor plugin. A while back, I left an offhand comment listing issues I saw as blockers (those that caused data transformation that would be hard to recover from at scale). This comment apparently received more attention than I expected it to, so now we’re partially focused on making sure those blockers are resolved.

And have we been fixing blockers! A non-exhaustive list includes:

The two remaining problems that cause me the most hesitation are:

  1. Unexpected content changes toggling Classic editor from Text to Visual to Text – When post content includes blocks (i.e. you’re opening a Gutenberg post in the Classic Editor), TinyMCE can mangle the blocks within the post. The solution is TBD; needs additional research.
  2. Gutenberg breaks “classic” posts w/ shortcodes by carelessly wrapping shortcodes into paragraph tags – This was partially fixed by correctly handling multi-line shortcodes in a block conversion. However, these multi-line shortcodes still end up with paragraph tags around them. The current suggestion to explore is running wpautop() and shortcode_unautop() on the server instead of TinyMCE.

If you’d like to save a point of reference, I have a working GitHub issue documenting these two and some other issues around block conversion, tables, and galleries. Help appreciated!

Posted on

Help with the Gutenberg Migration Guide at WCEU

This was originally posted on make.wordpress.org/hosting.

Looking for something to do at Contributor Day? We could use your help!

The Gutenberg Migration Guide is a crowdsourcing project to document WordPress Classic Editor customization points and their Gutenberg equivalents (if such exist). media_buttons is the quintessential example; whereas you might’ve used this action previously in the Classic Editor to register a button, it no longer exists in Gutenberg and the block inserter is its direct equivalent.

We want the migration guide to be as comprehensive as it can be. This is defined as:

  1. Identifying as many integration points as we can find. For instance, there are already 14 actions / filters listed. Some are commonly used, while others are not. As long as we have a good example for how the integration point is used, it makes sense to include in the guide.
  2. Whenever possible, documenting how feature parity can be achieved with Gutenberg. Some integration points do already have Gutenberg equivalents. Others don’t yet, and that’s alright.

You can help make the migration guide more comprehensive. If you don’t have any examples of your own to include, here are a couple of places you can start looking:

Everyone can contribute to the migration guide, regardless of skill set. All you need to do is open a new GitHub issue and report the incompatibility you’ve found. Screenshots and GIFs are tremendously helpful. If you know the underlying problem, then please include that too. If all you know is that a given plugin’s feature doesn’t work in Gutenberg, no worries; simply open an issue and we can help track down the cause. Identifying examples of breakage are what we need help with most.

Feel free to join #hosting-community in the WordPress.org Slack if you have any questions, etc. Thanks for your help!

Posted on

High value Gutenberg issues

Want to have a huge impact on Gutenberg’s rollout to a larger number of users? Here are some high value issues that would benefit from a pull request over the next week:

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 #core-editor channel with any questions you might have.

Posted on

Getting your site ready for Gutenberg

Still need guidance getting your site ready for Gutenberg?

On Tuesday, June 5th at 10 am PT, I’m heading up a webinar with Pantheon to cover how you can get your site ready. More specifically, we’ll cover:

But wait, there’s more! The webinar is just one in a series of five, including Mel Choyce and Josh Pollock. You should sign up so Tessa and I aren’t terribly lonely on June 5th.

Posted on

Gutenberg and the REST API, early May

This post originally appeared on make.wordpress/core.

Since I last wrote two weeks ago, we’re making progress! Key achievements for Gutenberg and the REST API include:

  • Support for who=authors was added to GET wp/v2/users, making it possible to accurately query for authors. WordPress, for better or for worse, defines an author as user_level!=0. See WordPress/gutenberg#6361 for the context on why we can’t add this logic client-side (#42202 for WordPress 4.9.6).
  • Improved performance for the _fields= query parameter (e.g. GET wp/v2/pages?_fields=id,title) by ensuring WordPress core will only process the fields requested for the response. Notably, this helps us avoid running the_content when we don’t need to be (#43874 for WordPress 4.9.7).
  • Minor enhancements to reflect existing WordPress behaviors:

The “Merge Proposal: REST API” GitHub milestone represents the distance we still need to close. Slowly, steadily, we’re bridging the gap, but we could use your help. Here are some of the issues we’re still working through:

  • To ensure all necessary data is available to Gutenberg, we’ve settled upon permitting unbounded per_page=-1 REST API requests for authorized users. This landed for GET wp/v2/users (WordPress/gutenberg#6627), is in-progress for GET wp/v2/(pages|blocks) (WordPress/gutenberg#6657), and needs to be addressed for categories, tags, and custom taxonomies. We also need to patch core with this enhancement (#43998 for WordPress 4.9.7?)
  • Capabilities can’t be processed directly client-side (WordPress/gutenberg#6361), so we’ve introduced a new targetSchema concept to communicate which actions a user can perform. See it in action with wp:action-sticky (WordPress/gutenberg#6529) and wp:action-assign-author (WordPress/gutenberg#6630). There are a few other actions we will need to work out, and then we’ll need to patch core (no ticket yet).
  • Adam is putting together an improved autosaves implementation (WordPress/gutenberg#6257) that I literally cannot wait to see complete. I’m sure he could use some help testing in the near future.
  • Felix is implementing a WP_REST_Search_Controller endpoint (WordPress/gutenberg#6489) to power the link search UI.

Join us tomorrow, Thursday, May 10 at 17:00 UTC in #core-restapi office hours if you’d like to chat through any questions you have.

Posted on

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.

Posted on

Summary of Gutenberg Plugin Compatibility Database results to date

A quick run-through of where we’re currently at with the Gutenberg Plugin Compatibility Database.

Since announcing the database on March 1st, 70 people have been granted testing status. However, of 5000 total plugins, we’re still at 4139 untested plugins. No companies have stepped up to contribute a significant amount of person-hours.

Of the 861 tested plugins:

  • 219 (25.44%) are compatible.
  • 518 (60.16%) are likely compatible.
  • 25 (2.9%) are likely not compatible.
  • 39 (4.53%) are not compatible.
  • 60 (6.97%) are in “testing”, which means someone started test and abandoned the process.

Notably, this data is largely biased by the “likely compatible” results. For the most part, these are plugins I pre-screened (e.g. caching plugins) prior to March.

In the original data set, 18 (28.125%) of the 64 incompatible and likely incompatible plugins were updated in the four weeks prior to March 1st. This means the majority are on slower development cycles.

Of the 64 incompatible and likely incompatible plugins, the reasons include:

  • Missing Add Media and TinyMCE buttons (NextGen, WPForms, Formidable, FooGallery, Page Scroll to ID and others).
  • Missing QuickTag buttons (Quick AdSense).
  • Meta box doesn’t display at all (Page Links To, Revision Control).
  • Semi-live preview of SEO title doesn’t work in Gutenberg (All In One SEO).
  • Custom Short or Long Product Description fields don’t appear at all (WooCommerce).
  • Featured thumbnail previews aren’t being generated (Auto Post Thumbnail).Whitescreen of death (qTranslate X, CKEditor).
  • Registers a CPT with editor support that doesn’t include show_in_rest=>true (Portfolio Post Type)
  • Adds section to Media Library that isn’t displayed in Gutenberg (Add From Server).
  • Access restriction from plugin not applied in Gutenberg (Advanced Access Manager).
  • Specifying custom gallery image links isn’t applied in Gutenberg (WP Gallery Custom Links).
  • Doesn’t log changes made in Gutenberg (WP Security Audit Log).

Next steps are to be determined. “Try Gutenberg” represents an opportunity to generate more data (out of support forum requests). However, we need a workflow for capturing that data.