Clarify and document backward compatibility policies for block development

[t-hamano]

Related PR: #64121

Currently, there are various statuses for blocks, so we need to clarify what backward compatibility policy should be applied depending on the status.

Block Statuses

Currently, blocks in the Gutenberg plugin have five statuses:

• Stable Blocks: Available by default, and the latest version of the block is bundled with core with each WordPress release.
• Gutenberg-only Blocks: Blocks with __experimental:true defined in block.json. These blocks are only available by default in the Gutenberg plugin and do not ship with core.
• Gutenberg-only Blocks (only available in the site editor): Blocks with __experimental:"fse" defined in block.json. Only available in the site editor. These blocks are only available by default in the Gutenberg plugin and do not ship with core. Two deprecated blocks (core/post-comment、core/comment-author-avatar) belong to this category.
• Experimental Blocks: Blocks with __experimental:true defined in block.json and available when the "Enables experimental blocks on a rolling basis as they are developed." setting is enabled. Currently, four accordion-related blocks belong to this category.
• Form Blocks: Blocks with __experimental:true and available when the "Blocks: add Form and input blocks" setting is enabled. Currently, four form-related blocks belong to this category.

Backwards compatibility processes

Here's what we should do at least in stable blocks:

1. Block Deprecation: This is mainly needed to ensure that blocks that already have content don't break when the save function is updated. See: Deprecation – Block Editor Handbook
2. Create Fixture: This is needed to ensure that the block deprecation process works with different versions of the block. See: Full post content test fixtures
3. CSS Styling: Even if we update a save function, the block deprecation process won't run unless the user updates the content that contains that block. So, for example, if we update a save function and style it with a new CSS class name, the new CSS class name won't exist in the user's content. So we need to maintain the old CSS selectors and styles to avoid breaking users' old HTML. Example Code

What backward compatibility policy do we apply to these blocks?

For stable blocks and Gutenberg-only blocks, we are responsible for enforcing all of the backward compatibility policies mentioned above, but for the other three statuses, I don't think we have clear guidelines yet.

I propose the following status organization and rule formulation:

Stable Block and Gutenberg-only blocks

For blocks that are available by default when the Gutenberg plugin is enabled, namely Stable Block and Gutenberg-only blocks, we strictly enforce the backward compatibility policy mentioned above.

This policy has been and should continue to be adhered to in the future.

Gutenberg-only Blocks (only available in the site editor)

It no longer makes sense to limit the use of blocks to the site editor. I propose to remove "fse" as a value for the "__experimental" field.

Currently, only two blocks fall into this category: the deprecated core/post-comment and core/comment-author-avatar blocks.

Experimental Blocks

For blocks in this category, the checkbox has a clear warning, so we do NOT apply the backward compatibility policy mentioned above.

Form Blocks

The biggest uncertainty is how to handle this block. We may not have clearly explained what issues users might encounter in the checkbox description, but we have tried to maintain backward compatibility as much as possible.

In my opinion, more iterations and breaking changes are needed to stabilize form-related blocks. I believe that maintaining backward compatibility during this process will be very difficult.

I propose to remove the Form blocks checkbox and include form blocks in the Experimental blocks setting. This means that the aforementioned backward compatibility process will no longer apply to form-related blocks.

[mikachan]

Thanks for writing this up!

In addition to your proposals, I'd also like to see Gutenberg-only blocks and Experimental blocks merged into one category. As far as I can see, the only Gutenberg-only blocks we have are Time to Read and Table of Contents. I think we should stabilise both of these blocks (related: #53776, #42229), and then, going forward, ensure that any blocks that declare __experimental:true in their block.json files are also included behind the __experimentalEnableBlockExperiments flag (it would be nice to handle this programmatically, too).

I propose to remove the Form blocks checkbox and include form blocks in the Experimental blocks setting.

I'm in favour of this, as well. I don't think we need to separate out the Form blocks into their own category, and they can be included with the other experimental blocks.

[t-hamano]

Tnanks for the feedback!

In addition to your proposals, I'd also like to see Gutenberg-only blocks and Experimental blocks merged into one category.

This means that any blocks added to the Gutenberg plugin will definitely ship with the next WordPress release. Is this ok?

[mikachan]

This means that any blocks added to the Gutenberg plugin will definitely ship with the next WordPress release. Is this ok?

I think this is fine, as long as they're stabilised before we remove __experimental:true. It would be amazing if we stabilised both blocks in time for WP 6.9, but I think it's OK if this doesn't happen at the same time for both blocks (I think we're quite close with the Time to Read block, but the Table of Contents block seems to require comparatively more work).

In other words, I don't think we need to merge Gutenberg-only blocks and Experimental blocks immediately, but I'd like to stabilise both of these mentioned blocks (which doesn't have to happen at the same time), and then going forward try not to have any blocks that declare __experimental:true without also being included in the __experimentalEnableBlockExperiments flag.