Gallery block: 5.9 Beta block migration edge case

[glendaviesnz]

There have been some issues with getting block deprecations to run reliably for the old Gallery block format to the new innerBlocks format ready for release in the WP 5.9 Beta .... but we think we now have the main issues sorted 🎉 , with one edge case, which we think is so unlikely that we don't believe it is a problem, but we would appreciate some more 👀 on it to confirm our assumptions.

We are also using a slightly non standard approach to fix one of the main blockers that we had, so it would also be good to get more 👀 on that as well.

Background

The new Gallery innerBlocks format uses a nested <figure> structure, which was incompatible with the use_balanceTags option in WP < 5.9 as the force_balance_tags method did not recognise figure as self nestable. This causes any of the new Gallery blocks added on a site with this option enabled to break on post save.

This issue has been fixed for 5.9. However, with turning on the auto-migration of all Gallery blocks to the new format on edit in Gutenberg 12.1 (which will be cherry picked into 5.9) we need to account for sites that may have use_balanceTags on and install Gutenberg 12.1+ before upgrading to WP 5.9.

The fix

To fix this we have kept all of the v1 block code in place and we are checking for 1 !== $use_balance_tags || is_wp_version_compatible( '5.9' ) and only migrating to the new version of the block if a site meets this criteria.

Because the deprecations/migration pipeline runs very early in the editor startup process, and before the likes of the experimental flags are loaded into the store, we have had to run this check and assign it to a var very early in the editor script loading process. This process works reliably in all of our testing, and it is contained on the compat scripts file with a clear note about the versions after which it will be removed.

It would be good to know if anyone can see any gotchas with this approach.

The edge case

The one edge case we have not covered is if someone has:

• The use_balanceTags option turned off
• Installs Gutenberg 12.1+ on WP < 5.9
• Adds a Gallery block to a post
• Then turns the use_balanceTags option on

In this case the user blocks will show as invalid when reloaded in the editor.

In our testing, trying to account for this edge case makes the deprecations code much more complicated and less reliable, and also this is a very edge edge case in that to encounter it :

• a site has to have been installed <= 2015 as the use_balanceTags option was deprecated some time around then, and doesn't appear as an option to set in WP Admin for sites newer than this
• Has to be running Gutenberg 12.1+ on WP < 5.9
• For some reason decides to turn use_balanceTags on

For these reasons we don't think that this is a backwards compatibility edge case that is worth trying to account for in the deprecations code. There is a non-code fix for it which is for the site to turn use_balanceTags back off, or to upgrade to 5.9+.

Let us know if we have overlooked anything in our assumptions about this edge case..

[glendaviesnz]

One suggestion that has come in is to add an options update filter to prevent people turning that option on if they are not on 5.9, eg.

diff --git a/gutenberg.php b/gutenberg.php
index d336aa1f3d..71061c5926 100644
--- a/gutenberg.php
+++ b/gutenberg.php
@@ -71,3 +71,26 @@ function gutenberg_pre_init() {
 
 	require_once __DIR__ . '/lib/load.php';
 }
+
+/**
+ * Prevent use_balanceTags being enabled on WordPress 5.8 or earlier.
+ *
+ * @since 12.1.0
+ *
+ * @param int $new_value The new value for use_balanceTags.
+ */
+function gutenberg_use_balancetags_check( $new_value ) {
+	global $wp_version;
+
+	if ( 1 === $new_value && version_compare( $wp_version, '5.9', '<' ) ) {
+		echo '<div class="error"><p>';
+		/* translators: %s: Minimum required version */
+		printf( __( 'Gutenberg requires WordPress %s or later to function properly with <code>use_balanceTags</code> enabled. Please upgrade WordPress before enabling <code>use_balanceTags</code>.', 'gutenberg' ), '5.9' );
+		echo '</p></div>';
+
+		return 0;
+	}
+
+	return $new_value;
+}
+add_filter( 'pre_update_option_use_balanceTags', 'gutenberg_use_balancetags_check' )

so we will do some testing around that next week.