Exploration: Managing backwards compatibility across Gutenberg Versions

[nerrad]

Context: p90Yrv-1gv-p2

Summary

As the blocks team starts looking to the future and building blocks that do newer and more interesting things in the new realm of WordPress development, it increasingly becomes apparent that it's tough to keep up with the rapid iteration happening in Gutenberg development. While currently WooCommerce blocks require version 5.0 of WordPress and (including the pending WP 5.3 release) that's only 3 versions of back-compat support. It's actually equivalent to supporting 19 versions of Gutenberg releases in that same period of time (Gutenberg 4.7 went into WordPress 5.0 and Gutenberg 6.6 is landing in WP 5.3).

The pace of development has been incredible in the Gutenberg project and has brought many awesome improvements in the underlying packages shipped with WordPress, new blocks, a11y improvements, and performance games. Many of these changes impact not only what we can build for WooCommerce blocks, but also how we build them. As a result, this also impacts backwards compatibility.

A tension we face with WC-Blocks development, is that maintaining backward compatibility for primarily server side apis, is much different than maintaining backwards compatibility for client side apis. Client side involves enqueuing scripts and style bundles that can change significantly between versions and while the GB team has done an admirable job in preserving apis and behaviours along all the versions that are released, the reality is that if we want to provide the latest improvements to end users of our blocks, it's much more difficult to progressively enhance relatively consistent behaviour across multiple WordPress versions.

Next steps

Due to the dilemma introduced above, I'm doing some exploration around a possible solution for WooCommerce blocks. This solution involves:

• Preserving existing blocks behaviour across the minimum WP version blocks currently support (WordPress 5.0) and only bump that minimum requirement for existing blocks when WC core bumps it's minimum WP core requirements.
• New blocks requiring the latest Gutenberg behaviour (as determined on a case-by-case basis) will have minimum WordPress version requirements. That means to use that block, your WordPress environment would need to match the minimum requirements for that version.

Practical considerations:

• We want to isolate any conditional loading/initialization so that when WC core bumps it's minimum WP version requirements, we can remove any legacy code retained for back-compat reasons.
• We need to monitor the dependency chain of components to ensure existing blocks don't use consume a component that requires a higher version of WordPress.
• The above may necessitate doing "legacy" builds for older versions of WordPress supported so that we can load those bundles in those environments instead of the new bundles.
• To keep code churn to a minimum (and isolate branches), only have separate forks/branches of a component when needed and simply consume the correct component for an environment in a built bundle (which can be done via webpack aliasing for imports).
• We'll want to limit what branches we maintain to at most two (let's see if we can do that). This means if we introduce a block using components that requires WP 5.3, then any legacy build (if necessary) would be loaded for WP5.0-WP 5.2 and the main build will be loaded for WP 5.3+. We would not introduce a block with new WP version requirements greater than 5.3 until Woo Core bumps it's minimum version requirement for WP to 5.3 (thus we can eliminate the legacy build).
• In cases where we have existing blocks utilize legacy components in a legacy build but consume newer components in the main build, we'll have to ensure that primary block behaviour is the same so there are no invalidation issues and the transition for the merchant is painless (ideally, they don't even notice it) when they update their WordPress version on their site.

Exploration items

The following is a list of specific things to explore as a part of the solution and with the practical considerations in mind. It is not exhaustive and will likely be updated as I work on things.

• use an alias for components used by blocks so that the build step can point the alias to a different path for specific builds. This will be needed when/if we do legacy builds. (see Introduce legacy build system and new aliases #1018)
• pass along the wp version on wcSettings and expose it so we can use that for conditional registration of blocks client side. (Expose wp_version on settings api and provide a js version compare function #1033)
• php side introduce a system for both indicating what WP version a block supports and conditionally registering/loading it in that version.

[issue-label-bot]

Issue-Label Bot is automatically applying the label type: feature request to this issue, with a confidence of 0.74. Please mark this comment with 👍 or 👎 to give our bot feedback!

Links: app homepage, dashboard and code for this bot.

[nerrad]

@mikejolley, @pmcpinto and @Aljullu - I feel I've done enough in this exploration to demonstrate a viable path forward for the following:

• client side we can have a requirement on code only executing in certain WP environments (via getSetting( 'wp_version' ) and compareVersions. This would be useful for just preventing certain blocks from registering.
• client side we have a legacy build system that allows us to build an alternate set of build bundles to load server side given a set of constraints (usually specific wp version). I can document this system in a p2 but it's also documented in assets/legacy/README.md.

Next Steps

• Do we want to roll with this?
  • If yes, then I'd like to make the All Products block require WP version 5.3 (which would allow me to use the latest wp.data api and the wp.data-controls package for our store needs.
  • If no, then I can revert the pull adding the legacy build system.
• Currently we're not actually building the -legacy bundles but just have the system in place, I think we can hold off actually building the files until we have definite need (for example, we update components to use wp.data stores but need to load older versions of those components in pre-5.3 environments).
• When the above becomes necessary we can also implement the php side code for conditionally loading the legacy bundles.

For this point in the original post:

php side introduce a system for both indicating what WP version a block supports and conditionally registering/loading it in that version.

I don't think we need it. The reason being is that blocks won't show up as available unless the client side registration runs. We can revisit this if it becomes a problem but I'd like to have a chance to refactor how blocks are loaded before tackling this specifically.

Looking forward to feedback/questions etc on this!

[pmcpinto]

@nerrad if we move forward with your suggestion, I was thinking that it could be done after this 6-week cycle: during the 2-week cool-down or in the upcoming cycle. What do you think?

[nerrad]

I was thinking that it could be done after this 6-week cycle: during the 2-week cool-down or in the upcoming cycle. What do you think?

It depends on whether you want the All Products block released at the end of this cycle and what version requirement it will have. The primary impetus for this was to figure out a way to make a block dependent on a WP version separate from other blocks. The wp.data store work I'm doing to support All Products block will require WP 5.3+.

To be clear, with #1018, and (soon) #1033 in place, a significant chunk of the logic required for this is in place.

[pmcpinto]

It depends on whether you want the All Products block released at the end of this cycle and what version requirement it will have.

Ideally we should have that block ready for release at the end of this cycle. It might take a while until 5.3 has a good market share, but I see the WC Blocks feature plugin as a way to experiment and develop new blocks before merging theme into Core. So if using the latest WP version on some block would allow us to move faster, I think that we should go for it.

[Aljullu]

@nerrad the path you explained looks good to me.

Do we want to roll with this?

I vote for it. 👍

I don't think we need it. The reason being is that blocks won't show up as available unless the client side registration runs. We can revisit this if it becomes a problem but I'd like to have a chance to refactor how blocks are loaded before tackling this specifically.

If we don't implement it, does that mean we would be loading the all-products.js file in the editor for WP 5.0-5.2 even if the block is not going to be registered? As I understand it, a PHP solution would allow us to avoid loading the file entirely, which sounds like a better solution, no?

[nerrad]

If we don't implement it, does that mean we would be loading the all-products.js file in the editor for WP 5.0-5.2 even if the block is not going to be registered? As I understand it, a PHP solution would allow us to avoid loading the file entirely, which sounds like a better solution, no?

Ya you're right (but for slightly different reasons as I gave it more thought). There's still going to need to be some sort of version check php side as well. For now, I might just do it in the block loader. There also will still need to be some php side work for loading -legacy assets vs non legacy assets depending on php version which I'll implement as needed.

I think in general the approach is sound, it will just probably need some further tweaks as we start implementing more broadly (which I'll be doing with the All Products block and the new data stores bundle).