Determine how plugin conflicts are handled and communicated

kevinwhoffman commented 6 years ago

Issue Overview

To understand this issue, it's important to think of the typical WordPress edit screen as the result of a collection of plugins and their meta boxes working together. At the point at which Gutenberg is merged into core, we have to deal with three types of plugins:

Types of Plugins

"Modern" plugins that adopt Gutenberg's block-based approach going forward.
"Legacy" plugins that explicitly undeclare support for Gutenberg. This means a developer is aware of Gutenberg and knowingly marks it as incompatible.
"Abandoned" plugins that may or may not work with Gutenberg, but there's no way of knowing for sure. These include bespoke websites with custom workflows that are unlikely to be migrated to Gutenberg. Think of freelancers who designed WordPress sites in the past couple of years and have since moved on.

The percentage of the overall pie that each of these buckets accounts for will certainly shift over the coming months and years, but it is safe to assume that a mix of the above plugin types will affect the majority of WordPress sites for the foreseeable future.

Challenges:

Determine which plugin type takes precedence when conflicts arise.
Communicate plugin conflicts as clearly as possible in both Classic and Gutenberg editors, so the user can decide which mode is right for them.

Context

In https://github.com/WordPress/gutenberg/pull/3554, a condition was established that would allow a single meta box to undeclare support for Gutenberg, therefore reverting the editor to Classic mode. That means if you have 10 plugins installed, and 9 out of 10 of them are ready for Gutenberg, it only takes a single meta box to revert the entire UI to classic mode.

While it's important to not break existing sites in the release of 5.0, it's equally important that we do not punish developers who do invest the time to modernize their plugins for Gutenberg. Especially as we look 6 months to a year down the road, we will begin to see plugins that are only built for Gutenberg. Allowing one old meta box to revert the entire editor to Classic mode will prevent access to these plugins while frustrating developers and users alike.

Recommended Solution

In the first few 5.x releases, perform a slow rollout in which we default to the Classic editor for all post types.
Accompany the slow rollout with clear communication around the arrival of Gutenberg, so that users know it has arrived before they see take over the editor screens they are used to.
Allow the editor to be toggled between Gutenberg/Classic mode from within the edit screen. That way if something is broken, the user has immediate access to revert it back.
It's important that this toggle only affect one post type at a time, since each post type will have different meta boxes and different compatibility issues.
Clearly display an admin notice in both Classic and Gutenberg editors that communicates which plugins are incompatible with the currently selected editor for that post type.

We have an unavoidable transition period ahead of us, but if done carefully, we can guide users through it and ultimately towards a future where the majority of that WordPress plugin pie is comprised of modern plugins that are Gutenberg-ready.

gidgey commented 6 years ago

From a marketing standpoint, it's important to make an effort to also educate the General Population.

Clients and developers should be aware of this transition(less) period. Continuing to call it an editor is misleading. I had several conversations with plugin developers at WCUS who were completely unaware of the drastic impact Gutenberg will have on their past and current website builds as well as plugins.

kevinwhoffman commented 6 years ago

From a marketing standpoint, it's important to make an effort to also educate the General Population.

I agree @gidgey. Development oftentimes gets the focus when we discuss roadmaps, but marketing, communication, and on-boarding are all part of the overall challenge that I would summarize as "managing expectations."

mor10 commented 6 years ago

This is why I still think making 5.0 a breaking change between "WP Classic" and WP is needed. An editor fallback prohibits future development of Gutenberg outside the editor. Providing a clean method for falling the application back to a stable pre-Gutenberg release is the only solution I've seen so far that doesn't introduce new or entrench existing legacy problems. Radical, but definitely something that needs to be discussed.

kevinwhoffman commented 6 years ago

This is why I still think making 5.0 a breaking change between "WP Classic" and WP is needed.

A clean break would be my preference as well, but I'm also trying to read the landscape and see that it's highly unlikely. If any of the leads or contributors thinks it's a possibility, please feel free to correct me.

An editor fallback prohibits future development of Gutenberg outside the editor.

Whatever fallback conditions ship with 5.0 don't need to be (and should not be) permanent. For example, we can cater to the Classic editor in 5.0 since we know that existing plugins are most likely to work with it. However as time goes on, more plugins will become Gutenberg-compatible. In fact we'll start to see plugins that only work in the Gutenberg editor.

But ultimately these fallback conditions cannot be automated because different plugins mean different things to different workflows. That's why I'm suggesting the slow rollout where each user can test Gutenberg on their own site with their own mix of plugins without feeling locked in.

pento commented 6 years ago

I tend to view this as one part of a holistic and ongoing approach to providing a shiny new Gutenberg experience for as many people as possible.

As you noted, the current behaviour, as implemented in #3554, is to fall back to the classic editor when a meta box deliberately declares that it doesn't work in Gutenberg. This is very much a first step for plugin developers to provide Gutenberg support - they can ensure their plugin continues to work immediately after WordPress 5.0 is released.

As time goes by, however, it's expected that plugin developers will add Gutenberg support - either by making their existing meta boxes work in Gutenberg (so they can set their __block_editor_compatible_meta_box flag to true), or by replacing their meta boxes with blocks (so they can set their __back_compat_meta_box flag to true). If a plugin has a meta box that doesn't work in Gutenberg, but is only there for back compat, then it won't cause a fall back to the classic editor.

This isn't the only possible flag for falling back. We could potentially maintain a list of scripts or plugins that are known to cause errors, and fall back when they're detected, even if the plugin hasn't been updated to deliberately declare themselves incompatible with Gutenberg.

As plugins are updated, we can change the default behaviour for meta boxes that don't work with Gutenberg. For example, instead of falling back to the classic editor, we might stay in Gutenberg, and display a warning that a meta box belonging to plugin X is not being rendered, giving the user an option to manually fall back. Following that, we may start requiring the classic editor plugin to be installed before falling back. Etc, etc. This is obviously a little bit speculative, but you see the path that we can follow.

Naturally, a responsible plugin developer would want to ensure their users have the best experience in the modern Gutenberg-y world, so for a time, will probably be maintaining both a classic and a Gutenberg version of their code. As the majority of users will be on Gutenberg from day 1, however, it's quite reasonable for the classic version to be maintained for bug fixes only - feature work can quite rapidly move to the Gutenberg interface.

The intention is that causing a fall back is something a plugin developer wants to avoid. To begin with, this is a simple as showing the end user which of their plugins caused a fall back. As time passes, the plugin causing a fall back becomes more of an inconvenience (encouraging users to switch to an alternative), and can even be weighted appropriately in the WordPress.org plugin directory - causing a fall back becomes a negative marker that conversely allows responsible plugin developers to move up the rankings.

gidgey commented 6 years ago

“As the majority of users will be on Gutenberg from day 1, however, it's quite reasonable for the classic version to be maintained for bug fixes only - feature work can quite rapidly move to the Gutenberg interface.”

This is quite the presumption. Many agencies, for example, wait to upgrade on major releases until the first Point release.

pento commented 6 years ago

"Day 1" is a little hyperbolic, it's more like "within the first quarter", but the assumption is sound. The majority of WordPress sites update to the latest major version within a few months of release (millions of sites already choose to update automatically for major releases), and generally only use plugins that either aren't affected by Gutenberg, or will work correctly with it on the day WordPress 5.0 is released. It's not at all hyperbolic to say that the vast majority of WordPress sites that upgrade to WordPress 5.0 won't see a fall back.

It's worth remembering that the fall back mechanism is primarily targeted at two sets of sites:

Agency built sites, which are more likely to have custom, complex work flows that require more effort to upgrade.
Sites that use plugins from the long tail, which are less likely to be consistently maintained.

For the former, upgrading to WordPress 5.0 can be as simple as rolling out the Classic Editor plugin for now, and working on an appropriate transition plan on a timeline that suits both the agency and the client.

For the latter, we're able to provide the opportunity, information, and incentives for plugin developers to upgrade. We can also tweak this as we go, to get as many existing plugins upgraded as is possible.

gidgey commented 6 years ago

Thank you for the clarification, Gary. As a Marketer, I can’t help but be concerned about perception which is, arguably, reality.

kevinwhoffman commented 6 years ago

@pento Thanks for your thoughts on this. I agree with the general approach you've laid out, which seems to favor the Classic editor early on and gradually shift towards Gutenberg as market share and plugin support increases.

It's not at all hyperbolic to say that the vast majority of WordPress sites that upgrade to WordPress 5.0 won't see a fall back.

I agree that the majority of sites will not see a fallback, but that's because the current conditions require a plugin to explicitly undeclare support in order to cause the fallback. Most plugins won't do that. However I would not take that as a sign of compatibility. For example, I have several meta boxes on existing sites that do not cause a fallback, but they also don't save data when in Gutenberg.

As you noted, the current behavior, as implemented in #3554, is to fall back to the classic editor when a meta box deliberately declares that it doesn't work in Gutenberg.

I understand this is only a first step, but I think it's a confusing and slippery slope to allow a single meta box to alter the entire editor experience. It will be difficult for users to grasp who is to blame or how to remedy the situation. I think a better first step would be to display admin notices that communicate which plugins are incompatible with the option to switch editors. Maybe that one plugin is worth reverting for the user; maybe it's not. Only the user knows that answer.

pento commented 6 years ago

I agree that the majority of sites will not see a fallback, but that's because the current conditions require a plugin to explicitly undeclare support in order to cause the fallback.

To clarify, the majority of sites won't see a fall back or broken functionality. The majority of WordPress sites use plugins that either don't touch the editor, or will have added Gutenberg support before WordPress 5.0 is released.

I think admin notices that communicate which plugins are incompatible with the option to switch editors is a better first step.

Why not both? There's already a warning displayed inside a meta box that causes a fall back, so the end user can directly see what functionality is affected by a plugin, and can make a more informed decision on how they would like to fix it. It currently only displays when WP_DEBUG is true, but I intend to change that before Gutenberg is merged.

kevinwhoffman commented 6 years ago

@pento I do think we should both notify the user and let them choose which editor fixes the situation relative to their setup. The behavior that I am arguing against is automatically reverting the entire editor based on one incompatible meta box.

Again I think we're generally on the same page here, we just need to think through the details of that conflict resolution and how clearly it is communicated to the user. Language like Gutenberg incompatible meta box, from the "%s" plugin. can be made easier to understand with a clear path towards resolution.

How does that user flow unfold?
What does the admin notice look like?
Where does it appear?
What is the language used to communicate conflict?

StaggerLeee commented 6 years ago

Whole army of coders working now on Gutenberg. You can also later when all is peacefull offer help to third party plugin developers. Meet in the half way, they do some work, you do half to help them adapt plugin(s) for Gutenberg.

Not common behaviour, but you like to make revolutions.

khromov commented 6 years ago

@mor10 Regarding "WordPress Classic" - in a similar vein, I believe making 4.9 a "long term stable" version is the way to go.

I wrote about it about a year ago, before intentions behind Gutenberg had been laid out clearly and it's more relevant now than ever: https://khromov.se/wordpress-needs-another-long-term-support-version/

gidgey commented 6 years ago

Because I'm not a developer I may be confused.

Please forgive this question:

Are you saying that ACF-generated metaboxes will still be visible, and therefore usable, with the Gutenberg Editor?

@pento wrote: "To clarify, the majority of sites won't see a fall back or broken functionality. The majority of WordPress sites use plugins that either don't touch the editor, or will have added Gutenberg support before WordPress 5.0 is released."

mor10 commented 6 years ago

@khromov https://www.linkedin.com/pulse/gutenberg-future-wordpress-conditions-success-morten-rand-hendriksen/?published=t

senlin commented 6 years ago

@pento

As time goes by, however, it's expected that plugin developers will add Gutenberg support - either by making their existing meta boxes work in Gutenberg (so they can set their block_editor_compatible_meta_box flag to true), or by replacing their meta boxes with blocks (so they can set their back_compat_meta_box flag to true). If a plugin has a meta box that doesn't work in Gutenberg, but is only there for back compat, then it won't cause a fall back to the classic editor.

That's all about plugins.

What about a site that a developer built for a client a few years ago that makes extensive use of meta boxes?

The moment 5.0 drops the developer would need to go into the site of the client and declare the __block_editor_compatible_meta_box false or upload the Classic Editor plugin?

That is assuming that the developer is still in touch with the client.

And if the developer is not then WordPress simply let's the site of that client (company, natural person, NGO, etc) fall apart?

And that will look bad on who?

kevinwhoffman commented 6 years ago

The moment 5.0 drops the developer would need to go into the site of the client and declare the __block_editor_compatible_meta_box false or upload the Classic Editor plugin?

I agree that this scenario is the one that is least acknowledged - that of a bespoke website without an active developer who has the awareness to install the Classic Editor plugin or set a flag. That is where conflict resolution and admin communication are most important.

I am optimistic that we can improve communication in these scenarios, but I'm less convinced that we can determine if there is a conflict in the first place since many "breakages" can be attributed to JavaScript or hooked actions.

senlin commented 6 years ago

since many "breakages" can be attributed to JavaScript or hooked actions

I don't agree. To me it is simple cause and effect.

Cause: WP 5.0 drops with Gutenberg

Effect: site content can no longer be edited by the completely unaware client

gidgey commented 6 years ago

Right

On Tue, Dec 12, 2017 at 3:16 AM Piet Bos notifications@github.com wrote:

since many "breakages" can be attributed to JavaScript or hooked actions

I don't agree. To me it is simple cause and effect.

Cause: WP 5.0 drops with Gutenberg

Effect: site content can no longer be edited by the completely unaware client

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/WordPress/gutenberg/issues/3902#issuecomment-351021757, or mute the thread https://github.com/notifications/unsubscribe-auth/AV3JZm7XVXBolr1x1uIctoXBickpuH4_ks5s_mCFgaJpZM4Q8qzn .

-- Bridget Willard (949) 370-4059 bridgetwillard.com

webtrainingwheels commented 6 years ago

I think the core team has to accept some of the burden for a successful transition, and not shift it all to plugin/theme developers with a hope/pray strategy that people will update their code in a timely manner.

I would like to see a dedicated "transition team", focused on providing resources and taking proactive steps in this area (and maybe I'm nominating @kevinwhoffman to be chair ;) ).

e.g. Could there be a Gutenberg-checker plugin bundled into an upcoming point release that devs and users can run on their code and be alerted about:
- what will break
- what will work, but sub-optimally
- how to fix
User feedback to devs based on these results could encourage faster updates and more awareness
Can there be any automation of migrating to Gutenberg? Extracting and porting over data etc (I'm not a dev so the terminology may be incorrect, but hopefully the point is clear)? If so, the transition team could work on providing these tools.

kevinwhoffman commented 6 years ago

what will break, what will work, how to fix...

As I mentioned above, our ability to automate conflict resolution depends on our ability to detect when something breaks. Since there are no restrictions on what meta boxes are allowed to do within the current edit screen, there are unlimited possibilities for them to break.

For example, one meta box may appear entirely functional but not save content correctly. Another meta box may not appear to work at all due to JavaScript errors. These are really difficult errors to detect and could result from a number of issues.

@youknowriad and I added a new section to the handbook that mentions some common compatibility issues, but to my knowledge that's just based on observation.

Maybe Riad has some ideas on detecting breakages?

youknowriad commented 6 years ago

I share @kevinwhoffman's opinion, it's really hard to automate the breakage detection. I think what's important is that people try their plugins and report issues if they find any. We then can categorize these issues and see what can be done for each category.

We could fix some of them
We could document the ones that can't be solved. Thanks @kevinwhoffman for the suggestion and the PR
If there's a way to provide an easy upgrade path for these, we should document it as well.

khromov commented 6 years ago

@youknowriad It's hard to automate breakage detection but not impossible. For example you could publish a "Gutenberg telemetry" plugin that uses the open-source error tracker from Sentry to record errors. It records all JS errors together with traces and should give a good indication of what breaks and in which browsers.

https://github.com/getsentry/raven-js

youknowriad commented 6 years ago

@khromov yep, these are great ideas, we could also use some automatic plugins introspection to detect common issues (outdated selectors, filters...). The same way tide works. Any contribution in this area would be greatly appreciated.

khromov commented 6 years ago

@youknowriad As far as telemetry goes, I think only Automattic would be able to pull it off, as I'm sure nobody wants to install a plugin that transmits data to some unknown entity. Regarding Tide, is the platform open in such a way that would allow for the automated tests you propose?

youknowriad commented 6 years ago

@khromov I don't know about tide, I heard it supposed to be open sourced at some moment. Especially, since it's moving under .org

wunderdojo commented 6 years ago

Here's a thought -- and this isn't meant to be facetious. Automattic is worth in excess of $1b. If upstarts like Wix can afford to advertise fairly heavily perhaps for a fairly major change like this Automattic can pony up a few bucks to make sure the general non-techy, non-developer user base is aware that there are cool changes coming that may require some adjustments on their part. Rather than expecting the indie developer to track down a client they haven't spoken to -- or earned money from -- in several years and tell them their spiffy WP site might stop working but hey, it's not my fault, I sold you a solid product, how about WP flips it so end users are reaching back out to the original devs saying "I heard about this change, is this something I need to do anything about?"

khromov commented 6 years ago

@youknowriad Will Tide be released soon enough then, considering the very short deadline until 5.0 drops? Even if they were to release some parts of it as open-source, will there be time to integrate and test?

rosswintle commented 6 years ago

I like the idea of:

themes and plugins declaring support for Gutenberg
site admins being offered the choice to start using Gutenberg once the active theme and all active plugins have declared support
site admins also having some setting to enable Gutenberg before the active theme and plugins declare support BUT with a big warning popup that tells then that their site may not be compatible with Gutenberg, and showing them how to go back if things break

I know WordPress is all about decisions rather than options, but I can't see how just enabling this when you update to v5.0 is going to be pleasant for anyone.

I use lots of SAAS (Software As A Service) products that have done big design or feature updates. They introduce them and provide education on them before turning them on. And in many cases they let you "opt in" during some kind of "beta" period before switching it on for everyone. Google do this with Calendar, Analytics, GSuite and so on. Mailchimp do this. I think Twitter did it with a big redesign once. I don't understand why WordPress isn't shipping it in default-off state in 5.0, giving simple options for switching. Warning and educating users about what might happen. And then enabling it for everyone in a later release.

danielbachhuber commented 6 years ago

I use lots of SAAS (Software As A Service) products that have done big design or feature updates. They introduce them and provide education on them before turning them on. And in many cases they let you "opt in" during some kind of "beta" period before switching it on for everyone.

My hunch is that much of this will happen in the 4.9.x range.

I don't understand why WordPress isn't shipping it in default-off state in 5.0, giving simple options for switching. Warning and educating users about what might happen. And then enabling it for everyone in a later release.

Decisions, not options :) Sometimes you need to swallow a difficult pill in order to move forward. There's a ton we can do to make the process less painful though, which is where we should focus our energy.

rosswintle commented 6 years ago

I don't think WordPress USERS should be made to swallow a difficult pill. Developers, yes; users, no.

aaronjorbin commented 6 years ago

Shipping it turned off by default for everyone would go against the WordPress philosophies. As a large group with a fluid membership, the philosophies allow us central tenants to fall back to and guide our decisions.

We have multiple months to iterate, and this includes iterating how we educate people. I fully think that in an upcoming 4.9.x release, Gutenberg will be promoted ( see https://core.trac.wordpress.org/ticket/41316 ).

Two relevant passages from the philosophies:

Every time you give a user an option, you are asking them to make a decision. When a user doesn’t care or understand the option this ultimately leads to frustration

If the next version of WordPress comes with a feature that the majority of users immediately want to turn off, or think they’ll never use, then we’ve blown it

danielbachhuber commented 6 years ago

I don't think WordPress USERS should be made to swallow a difficult pill. Developers, yes; users, no.

Sorry, that's not quite my intent.

In my opinion, Gutenberg should be so good that WordPress users are excited for it in WordPress 5.0. They should be looking forward to upgrading, so they can use an editing interface that's 10x better than what they currently have.

When the first iPhone came out, I was so excited that I paid $600 I didn't have because the iPhone was that much better than my Moto Razr. This is where we should be setting our sights.

We obviously have some work to do between here and there, but that's the opportunity. We don't get many like it.

rosswintle commented 6 years ago

In my opinion, Gutenberg should be so good that WordPress users are excited for it in WordPress 5.0

So, you're saying the pill shouldn't be difficult? Or it shouldn't be a pill, it should be a bar of chocolate? I'm so confused.

I any case, the discussion seems closed. Thanks for listening.

StaggerLeee commented 6 years ago

If the next version of WordPress comes with a feature that the majority of users immediately want to turn off, or think they’ll never use, then we’ve blown it

"Majority"..."turn off"...I read your philosophy as you force on Users something they do not want, regardless of Gutenberg.

aaronjorbin commented 6 years ago

"Majority"..."turn off"...I read your philosophy as you force on Users something they do not want, regardless of Gutenberg.

These are the WordPress project philosophies, not my personal philosophies. I would encourage getting to know them if you haven't as they are wonderful for helping to guide decision making. https://wordpress.org/about/philosophy/

kevinwhoffman commented 6 years ago

What's unique about Gutenberg is that the perception of the 80/20 rule changes based on the presence of themes and plugins. Rarely does a core feature affect third parties to this degree.

While it's easy to justify that Gutenberg is the right move for at least 80% of fresh installs, that statement is not so clear when you have to account for an endless combination of themes and plugins on existing sites.

The crowdsourcing of theme/plugin compatibility might help us get a better idea of that number, but predicting percentages of negatively affected users at this point is extremely difficult.

Zodiac1978 commented 6 years ago

So many assumptions in this thread. I already saw this on WordPress.com - if there is a new feature you could have hundreds of complaining users, there will be always the argument that there are much more people not complaining. It is completely irrelevant what the user want. It is relevant what Automattic/Matt wants to achieve.

Essentially the reply here is: Eat or die. Or in your words: "Embrace the problem."

timnolte commented 6 years ago

@zodiac1978 your comments are really not a helpful contribution. Do you have some ideas that will help us figure out the best transition plan?

danielbachhuber commented 6 years ago

If you want to help solve the technical challenges for compatibility, #4072, #4151, and #4186 are great places to start.

@kevinwhoffman Is there anything actionable you'd like to move forward with in this issue?

kevinwhoffman commented 6 years ago

Thanks, @danielbachhuber. The issues you reference are doing a great job of measuring Gutenberg compatibility, which is part of the issue I'm raising. The remaining uncertainties IMO are:

Communicating conflict when it is detected.
Allowing the user to revert to the Classic Editor if they encounter an undetected conflict. Automated testing can only go so far, and it doesn't account for custom themes/plugins which are most likely to create conflict without a developer to fix them.

Maybe @pento can update us on the state of conflict handling. Gary, have there been any changes to the fallback conditions or communication since this issue opened?

danielbachhuber commented 6 years ago

Thanks for the conversation, everyone.

Mitigating plugin (and site) incompatibility issues is an area we're actively working on. If you have specific, actionable steps you'd suggest taking, I'd encourage you to open a new issue with details. We'll continue to improve documentation and post updates on make/core as we progress.

WordPress / gutenberg