Document how and when to create fixtures for deprecated versions

[carolinan]

What problem does this address?

In the block editor handbook it is mentioned that "It is also recommended to keep fixtures which contain the different versions of the block".
From recent discussions it seems unclear wether this is recommended or if it should always be required.

Neither the handbook page for block deprecation or the page about fixtures describes the best practices for creating fixtures for deprecated versions, including the naming of the files.

Without a documented best practice for naming and describing deprecations, there are also inconsistencies in naming the fixtures.

See also #38445

[Mamaduka]

I agree. Including documentation about deprecation fixtures and mentioning this readme better in docs would be great.

[carolinan]

I'm finding it difficult to separate documentation for block development for Gutenberg, and for third party blocks.
In other words, I mean that how we are creating and naming fixtures for Gutenberg, may not be relevant for third party block development.

[Mamaduka]

In other words, I mean that how we are creating and naming fixtures for Gutenberg, may not be relevant for third party block development.

You're right. The handbook deprecation page is general for block development. The fixtures readme is mainly for the Gutenberg plugin, but plugin authors are free to adapt our techniques.

[carolinan]

We have this page in the contributor guide, which is completely separate:
https://developer.wordpress.org/block-editor/contributors/code/deprecations/

[ndiego]

We reviewed this issue today in the Block Editor Handbook Docs Scrub. I have written tons of deprecations for custom block and have no idea what a "fixture" is! 😅

@carolinan @Mamaduka do you both think we need this information in the BEH? Or should we just remove that singular reference to fixtures?

[Mamaduka]

I don't think this would be useful on the block deprecation API package. The fixture setup is Gutenberg-specific.

Maybe we can mention the readme somewhere in the Testing Overview?