Updating an Existing Block

Before You Start.

Carefully consider, do you need to update the block to achieve what you need? Will your update benefit all users of the block, or just the project you're working on?

There are so many hooks and filters available to blocks now that you should be able to hugely customize a block directly from your project (See the re-using an existing block page) and so feature updates to existing blocks should be rare. Bug fixes or general code improvement are more what we would expect here.

Things to Remember.

Keep in mind that blocks in this repository can be installed on multiple sites.

When you need to make any changes, make sure those changes (design and/or functionality) are applicable to any other sites and that you are improving upon the existing code, not just shoehorning in a feature that your current project needs.

Make sure that project-specific styles and data go into the project code and not the block code in this repo.

Static Block Deprecations.

When updating a static block — if we add any changes to the edit or save functions, we should deprecate the block to make sure we're not impacting the user experience. This is a great source of information with code examples ranging from simpler to more complex ones here: https://developer.wordpress.org/news/2023/03/10/block-deprecation-a-tutorial/

Dynamic blocks do not need deprecations, but do need careful consideration of the code changes you're making. How could your changes impact existing sites?

Testing Changes.

It is possible to get a list of WordPress.com Special Project sites that are using a block, ping Engineering Leads. You can use this list to quickly profile how other sites are using a block and test those cases against your changes.

Ensure you thoroughly test any changes in the latest Twenty-twenty-xyz theme, ideally you'll test the block on trunk and then switch to your development branch to ensure there's no breakages from that transition (simulating a plugin update).