Block API: Improve how blocks assets are versioned (#33075)

* Add version to generated `block.json` files. * Document new `version` field available in `block.json` * Clarify the case when the version is not set for assets * Update docs/reference-guides/block-api/block-metadata.md Co-authored-by: Grzegorz Ziolkowski <[email protected]>
WordPress · Jul 15, 2021 · f9a443c · f9a443c
1 parent 29d2f51
commit f9a443c
Show file tree

Hide file tree

Showing 3 changed files with 18 additions and 0 deletions.
diff --git a/docs/reference-guides/block-api/block-metadata.md b/docs/reference-guides/block-api/block-metadata.md
@@ -14,6 +14,7 @@ Starting in WordPress 5.8 release, we encourage using the `block.json` metadata
 	"icon": "star",
 	"description": "Shows warning, error or success notices…",
 	"keywords": [ "alert", "message" ],
+	"version": "1.0.3",
 	"textdomain": "my-plugin",
 	"attributes": {
 		"message": {
@@ -248,6 +249,20 @@ This is a short description for your block, which can be translated with our tra
 
 Sometimes a block could have aliases that help users discover it while searching. For example, an image block could also want to be discovered by photo. You can do so by providing an array of unlimited terms (which are translated).
 
+### Version
+
+-   Type: `string`
+-   Optional
+-   Localized: No
+-   Property: `version`
+-   Since: `5.8.0`
+
+```json
+{ "version": "1.0.3" }
+```
+
+The current version number of the block, such as 1.0 or 1.0.3. It's similar to how plugins are versioned. This field might be used with block assets to control cache invalidation, and when the block author omits it, then the installed version of WordPress is used instead.
+
 ### Text Domain
 
 -   Type: `string`

diff --git a/packages/create-block/CHANGELOG.md b/packages/create-block/CHANGELOG.md
@@ -6,6 +6,7 @@
 
 -   Plugin scaffolded with the `esnext` template requires WordPress 5.8 now ([#33252](https://github.com/WordPress/gutenberg/pull/33252).
 -   Block scaffolded with the `esnext` template is now registered from `block.json` with the `register_block_type` helper ([#33252](https://github.com/WordPress/gutenberg/pull/33252)).
+-   Add support for the new `version` field in the `block.json` metadata file ([#33075](https://github.com/WordPress/gutenberg/pull/33075)).
 
 ## 2.3.0 (2021-04-29)
 

diff --git a/packages/create-block/lib/init-block-json.js b/packages/create-block/lib/init-block-json.js
@@ -15,6 +15,7 @@ module.exports = async ( {
 	slug,
 	namespace,
 	title,
+	version,
 	description,
 	category,
 	attributes,
@@ -35,6 +36,7 @@ module.exports = async ( {
 				{
 					apiVersion,
 					name: namespace + '/' + slug,
+					version,
 					title,
 					category,
 					icon: dashicon,