Tutorial on block deprecation

[mburridge]

Discussed in #67

^{Originally posted by mburridge January 26, 2023}
If you make a change to the way that a block is rendered you will see the "invalid content" error message after the change.

This commonly occurs during development, and developers working with blocks are very aware of this and are used to dealing with it.

However, if you've already published a block and want to make changes to it in an update you won't want users to see the "invalid content" error message, which they will in each instance of the block across their site until recovery is done on each of them.

To circumvent this problem developers can "deprecate" the old version of the block.

A tutorial on how to deprecate a block, and when and why you should do it, would be a nice addition to the Developer Blog.

Reference:
Deprecation

[mburridge]

Resources

Documentation

• Deprecation - Block Editor Handbook

Videos

• Deprecation strategies for your custom Gutenberg blocks (Ryan Welcher)

Blog articles

• How to Deprecate Gutenberg Blocks
• How to deprecate code in Gutenberg editor blocks
• What Happens When Block Markup Changes? (Justin Tadlock)
• Gutenberg – Block Deprecation

Forums

• How do I properly deprecate Gutenberg block
• How can I deprecate an old version of my custom Gutenberg block, but keep the new version?

[mburridge]

Things to mention

• Why deprecate? - to provide graceful fallback for earlier versions of the block
• Primarily for static blocks - not needed for dynamic blocks as they don't have a save() function
• Benefit is for the content editor - avoids the 'invalid content' error message in the editor
  • front-end displays what's in wp-content for the post regardless
  • front-end only changes when the content is updated when the post is saved with new version of save()
• Each deprecated version of the block is an object, in the deprecated array, and has the following properties:
  • attributes
  • supports
  • save
  • migrate
  • isEligible
• Create a deprecated.js file and import it into index.js and use it in the registerBlockType function call
• Define each deprecated version as a const and reference in the exported array, e.g. [v3, v2, v1]

Simple demonstration

Scaffold a block with @wordpress/create-block
Create 3 posts - add the new block to each (plus some text "Test 1 / 2 /3 ")
Change text in save() and create first deprecation
Test in second post
Change text in save() and create second deprecation (also maybe change <p> to <div> - and view markup)
Test in third post
Test in first and second posts

[ndiego]

@mburridge I have a lot of deprecation horror stories, so looking forward to this piece. Will definitely be a very valuable addition to the blog! 💪

[mburridge]

I have a lot of deprecation horror stories

@ndiego please do share. It might be nice to have a section on pitfalls and gotchas to watch out for.

[ndiego]

Will do. I'll put together some examples next week 💪

[carstingaxion]

I would like to read about some nice ways to deprecate third–party blocks in favor of matured core blocks.

[mburridge]

A draft of the post is ready for review. Please test the code examples and that the iterations of the code and the deprecations of previous versions all work. Also any suggestions or corrections that might improve the post will be very welcome. Thanks.

[ndiego]

@mburridge I will read through today and add any comments I might have, but one thing that has tripped me up frequently is multiple deprecation issues. If there is more than one, sometimes the error message in the console can lead you in the wrong direction since it will only display the first error it encounters. So maybe a warning that the error message is helpful but only displays one error at a time and will not always be able to diagnose every issue.

[justintadlock]

This is well-written, as usual, @mburridge. I learned a ton and think this is exactly the kind of content that we need on the Developer Blog. I left a handful of in-doc comments.

I think my biggest note would be to try to break up the text a bit more with sections. I think this is pushing 2,000 words, so having a few headings sprinkled in there will make it easier to digest for readers.

I still need to do a run-through of the code, but the copy is pretty solid at this point.

[mburridge]

Thanks @justintadlock. I've broken up the wall-of-text with some headings, as per your suggestion. Let me know what you think.

[justintadlock]

@mburridge - The headings look good to me.

I've finished walking through the code and left my suggestions in the document. Overall, it felt pretty straightforward, and I successfully worked through each item. It was a really nice exercise for me since I haven't tried deprecation before. I'll definitely be more at ease with doing it for future blocks.

In addition to my mention of being precise about src/index.js vs. index.js, you could just mention earlier in the post that the reader will be working in the src folder. Just do it once instead of updating each file reference. I think that'd work better in this case.

[mburridge]

Glad you found it useful @justintadlock - I guess I must be doing something right! 😅

you could just mention earlier in the post that the reader will be working in the src folder

Great suggestion, thanks - I've done that.

[mburridge]

Public preview is now available for review.

[bph]

@mburridge Here is a publish checklist for you :-)

• Post Title in Sentence case
• Are Category or Categories selected?
• Are Tags identifies?
• Is there an Excerpt?
• Props added?

[mburridge]

The only thing outstanding is that I can't find Fabian Kägy's profile page for the props.

[bph]

You would need to do at it manually. The site only pulls from the list of users on this site, not on all of wordpress. It's a known issue, that hasn't been fixed yet.

[mburridge]

Okay, I found it in the end - he spells his surname differently in his username than in is actual surname 🤷‍♂️

[mburridge]

As far as I'm concerned this is ready to go @bph @abhansnuk @marybaum.

[mburridge]

"Block deprecation – a tutorial" now published.

[Bruse-Lee]

Why not implement a plug-in that traverses all articles containing the Attempt Block Recovery button and simulates users clicking to go to batch Recovery？