The REST API in WordPress 5.0. Solid set of improvements in these dev notes — thanks everyone who contributed!
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:
- It continues to work as expected. For example, an
enter_title_herefilter 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.
- It doesn’t work but there’s an equivalent alternative. Some of WordPress’ existing architecture doesn’t translate directly into Gutenberg. For instance,
media_buttonsis 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.
- 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.
Made my first WordPress commit this morning: r43680. It seemed like the moment would have more gravitas than it actually did. I made the commit, and then I went to make my kids’ breakfast. ¯_(ツ)_/¯
To the many commits to come!
On Wednesday, at WEA’s housing and transportation conference, I met an economist who’s studying competition and the shrinking number of small / medium-size businesses. New business formation isn’t behaving as most people would expect it to in a strong economy.
She thought open source, both software and methodology, might be a solution to make small and medium-size businesses more competitive. However, I argued the exact opposite: open source is a business strategy for an extreme form of taking the entire market.
I think one root cause of large companies growing larger is that technology lends itself to extreme operational efficiencies. With a technology company, the marginal cost of an additional customer is effectively zero. If Amazon can operate at 10x global scale with the same operational costs, it can take a smaller margin and still be very competitive. Traditional businesses can’t compete if they have a larger percentage of margin dedicated to operational costs.
So, if it’s true that more of the market is going to larger companies, is this worth solving for? And what are potential solutions? One result of current market dynamics is difficult to unwind: Amazon yields amazing customer value and worsening employment options (either by destroying jobs entirely or offering poorer wages).
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:
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.
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
If you’d like to replicate elsewhere, here’s the underlying build script:
“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:
Adding images to a post doesn’t also attach it Editing cases a huge number of revisions Category, tag, and taxonomy controls don’t respect the correct capabilities REST API: Attachments controller should respect “Max upload file size” and “Site upload space” in multisite(WordPress 4.9.8) Convert to Blocks not properly converting successive shortcodes (Gutenberg v3.3) New lines in shortcode content are ignored(Gutenberg v3.3)
The two remaining problems that cause me the most hesitation are:
- 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.
- 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
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!
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:
- 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.
- 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:
- Our plugin compatibility database has a good number of plugins marked incompatible. Some even have descriptions of the problems!
- The [Type] Plugin / Theme Interoperability and Backwards Compatibility labels in the Gutenberg GitHub repository have some number of reasonably documented conflicts.
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!
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:
- Persist custom CSS classes during block conversion when block supports additional classes
When a WordPress user converts existing HTML to a block, or manually edits the block HTML to include a class, we should persist their custom CSS class into the additional classes field.
- Autosaving somehow triggers a full save when metaboxes exist, causing too many revisions
Gutenberg 3.0 included a bunch of new autosave functionality that still needs some work. Track down this bug before Adam Silverstein does!
- Drag and drop uploading should respect WordPress multisite max upload size
We need to make sure file size is validated both client-side and server-side. Felix Arntz started a patch for core that we’ll want to land in Gutenberg first.