Viable Migration Plan for Minimum Viable Product

[bobbingwide]

Issue Overview

Consider the following:

According to WikiPedia, a minimum viable product (MVP) is a product with just enough features to satisfy early customers, and to provide feedback for future product development.

From the handbook

• Major releases add new user features and developer APIs.
• WordPress strives to never break backwards compatibility.
• It’s one of our most important philosophies.

Regarding feature plugin merge

Again, paraphrasing the handbook

• For feature plugins to be included in a release, they must be ready to merge at the beginning of the merge window.
• At that point, the release lead will review current feature plugins, and along with core developers, determine if they’re fully baked and ready for merging into core.

The release lead will look for a number of things, including:

• a strong and well-tested user experience,
• fully-baked design,
• core-quality code,
• positive feedback from the community,
• no major bugs or issues,
• and a belief that the feature belongs in WordPress core.

Current status

The current status appears to be that two of these items are failing the test.

• There is a lot of negative feedback from the development community
• and this is mostly because they can see so many ways in which use of the new editor can break a site.

So, we have to fix this.

Assumptions

Without a well considered and implemented migration strategy.

• Many sites will start behaving differently.
• This will be directly attributable to someone attempting to change content using the new editor.
• Users and developers will get very upset.
• And this will be bad press for WordPress.

Requirements - Summary

• There should be multiple levels at which the new editor can be enabled/disabled: installation, site, content type, user, content.
• Upon installation the system should attempt to determine whether or not the new editor is compatible with the existing system.
• This compatibility test should be repeatable; both automatically and manually.
• For every piece of content being edited the editor should attempt to determine whether or not it might alter the content in such a way that the site might break.
• Fully documented APIs should allow plugins and themes to extend the compatibility tests.
• The user should have the option to override the system's behaviour.
• The user should have the option to disable compatibility tests.
• The user's options should be respected.

Proposed solution - Summary

• For completely new single site installs the system may originally assume that it's OK to use the new Editor.
• For anything else, the tests should be run and the user given the choice to decide.
• The logic which is currently delivered in the classic-editor should be bundled into Gutenberg, catering for hybrid sites.

Reasons to use the Classic editor

Here's a short list of reasons to use the Classic editor instead of the New Editor.

• REST API not enabled.
• Incompatible meta boxes.
• Post type does not support 'content'.
• Content type is private.
• Content type does not have a UI.
• Editor incompatible with plugins or themes.
• Required capability not yet provided in the new editor.
• Use of the New editor will alter hand crafted or automatically generated content in such a way that it makes it unusable.
• User does not want to use the new editor.
• User cannot use the new editor.
• Device / browser combination not supported.
• REST API not working.

Tests for some of these are already implemented. Others have outstanding issues. I won't list them here.

Potential tests

Some potential tests that can be automated.

• 'the_content' filter hook definition has been modified from the WordPress default.
• 'replace_editor' already being hooked into.
• other significant action/filter hooks are different from the WordPress default.
• existing content contains stuff that New editor doesn't know how to deal with.
• user options for meta boxes which are not supported.
• test for a system wide configuration setting.
• JavaScript not enabled.
• post type does not support revisions.
• active version of plugin/theme known to be incompatible

Conclusion

• We don't want to break existing sites.

• We need to assess the potential risks.

• We need to prepare a risk management plan.

• And implement solutions that help reduce the likelihood of risks becoming issues.

• This has to be done as a prerequisite to the Merge Proposal.

• Most of the above should be taken into account

• This is no small task.

• But it can be done in parallel with the continuing development and refinement of the new editor.

• Once designed, most of the coding can be done by PHP developers.

• Allowing the REACT developers to continue working on the making the new editor the editor of choice.

Related Issues and/or PRs

• Scope & Features: MVP #4894
• All issues labelled with Backwards Compatibility
• All issues labelled with Accessibility
• Add a statement to docs regarding backwards compatibility #4738
• Quantify plugin and theme compatibility with Gutenberg #4072
• Determine how plugin conflicts are handled and communicated #3902

Todos

• Tests
• Documentation

[caraya]

I would add another two tests:

• Theme's functions.php is not empty. Then it's up to the user to figure out how much they need the custom functions versus Gutenberg functionality
• The theme has custom CSS styles. Again, let the user decide if they want to keep them and provide documentation as to where do global styles for a post move to in a Gutenberg scenario

[danielbachhuber]

@bobbingwide Do you have any suggestions on how we can make this issue actionable? What concrete steps can we take in the next few weeks to a month?

[danielbachhuber]

Closing — feel free to open new issues with specific actionable items.