Increment theme.json version to 3

[oandregal]

What?

This PR increments the theme.json version to 3.

Why?

We've added some new things to the theme.json schema, so we need to publish a new one to document in which WordPress version a specific setting can be found.

There's no modifications or removals in the existing schema, only additions:

• title top-level key
• patterns top-level key
• settings.color.defaultDuotone setting key

The behavior is the same as before, this serves to semantically mark the new files. This version change will be documented in the block editor handbook as well with a PR sent to the Gutenberg repository.

How?

Updates the version in the theme.json file bundled with Gutenberg and in the theme.json class.

Related PR to core at WordPress/wordpress-develop#2565

Testing Instructions

Does not have any effect at runtime.

[oandregal]

A related task I'll address shortly is to generate the v3 docs for the block editor handbook https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/

[gziolo]

@oandregal, is it necessary for the WP 6.0 Beta 1 release tomorrow?

[oandregal]

@gziolo this needs to be part of the WordPress 6.0 release. If we could have it in he Beta 1 tomorrow it'll be ideal so we don't have to worry for this anymore. Everything will work fine without these changes, so if we want to punt it for after the beta 1, that'd be fine as well.

[oandregal]

When I add a new reviewer another one is removed? I presume there's some kind of limit to the number of reviewers.

The pings in this PR are mostly for awareness for people that worked in this area: when the theme.json behaviour and/or the keys change we need to create a new version. In this case (2->3) there's only additions and not incompatible changes, so everything would work fine. Though it's important for matching a given schema change to the particular WordPress release that introduced it.

[oandregal]

I see there's an unit test failure for Block_Library_Comment_Template_Test::test_build_comment_query_vars_from_block_with_context_no_pagination, although not sure how is related to this PR.

[gziolo]

I see there's an unit test failure for Block_Library_Comment_Template_Test::test_build_comment_query_vars_from_block_with_context_no_pagination, although not sure how is related to this PR.

@adamziel noticed that, too. I guess it's related to the core commit WordPress/wordpress-develop@067d166. I'm investigating whether there are any differences in the implementaion in Gutenberg.

[adamziel]

@gziolo fixed that problem in WordPress/wordpress-develop@cab6fec

[youknowriad]

Do we really need to update the version for non-breaking additions?

[gziolo]

Do we really need to update the version for non-breaking additions?

I'm looking forward to the final decision. We are going to update release/13.0 on Tuesday morning (CEST) and use it to create wp/6.0 that's going to be used for the final version of npm packages for WordPress 6.0 Beta 1.

[youknowriad]

For block.json for instance, It evolved a lot (new keys...) since the v2 and we never needed to update the version number.

[aaronrobertshaw]

Thanks for putting this together @oandregal 👍

For block.json for instance, It evolved a lot (new keys...) since the v2 and we never needed to update the version number.

I expect we will have a larger number of 3rd parties leveraging theme.json. Would that increase the need to accurately match schema changes to WP releases that introduce them?

This probably also sets a good standard for maintaining versioning around theme.json as well.

---

✅ Theme.json migration doc update looks fine.
✅ Unit tests pass

• class-wp-theme-json-test.php
• class-wp-theme-json-schema-gutenberg-test.php
• class-gutenberg-rest-global-styles-controller-test.php

[aaronrobertshaw]

I appreciate this change is trivial but for consistency with the other theme.json classes and 6.0 related changes should we override this class in the same manner? I'm also ok with leaving it here.

[oandregal]

oh, you're right, should this land, we need to fix it.

[ajlende]

The JSON schema is loaded from the wp/x.x branch on GitHub, so once wp/6.0 is created, the new JSON schema will be available at https://schemas.wp.org/wp/6.0/theme.json. Updating the version becomes a breaking change, so theme authors will have to update that even though nothing else needs to change. So from the JSON schema perspective, I'd say that we should keep "version": 2 and not increment the value.

[oandregal]

We don't need this for anything to work and themes don't need to be adapted either. Though, I was under the impression that we wanted a new version for each theme.json schema with changes, so we could say, for example, patterns or defaultDuotone was added in version 3, so there was clarity for theme authors.

How would we provide this clarity for theme authors if we don't do this? 🤔

The keys/sections that are not supported in a given runtime are ignored. For example, a theme.json for WordPress 5.8 needs to use settings.border.customRadius (v1); for WordPress 5.9 and above, the v1 still works but the v2 uses settings.border.radius. If someone uses the v2 names in 5.8 they'll do nothing. Same for the patterns key in WordPress 5.9: it doesn't work.

I'm struggling to see how to clarify this for theme authors if we don't have versions. An alternative is to deemphasize versions in the block editor theme.json schema docs and follow instead the model of the block API docs: sections per key. For each key, we need to document which runtime (WordPress version) supports it.

Is this any better?

[youknowriad]

For me the apiVersion is not about additions, it's only about breaking changes. Whenever we introduce a feature that is likely to introduce breaking change, we introduce a new version that way we don't break anything for existing themes unless they opt-in (update version) for their theme.

The keys/sections that are not supported in a given runtime are ignored. For example, a theme.json for WordPress 5.8 needs to use settings.border.customRadius (v1); for WordPress 5.9 and above, the v1 still works but the v2 uses settings.border.radius. If someone uses the v2 names in 5.8 they'll do nothing. Same for the patterns key in WordPress 5.9: it doesn't work.

This is a valid use-case because it's a breaking change, if they don't change the version, the old key won't work.

Changing the apiVersion on each addition likely means that themes will have to play catchup with core and update their themes with each new version even if they don't make any changes. The alternative is them not updating the version but the new key still works (If I'm not wrong, even if my version is 2, the new keys will continue to work, so it's incoherent)

[oandregal]

The alternative is them not updating the version but the new key still works (If I'm not wrong, even if my version is 2, the new keys will continue to work, so it's incoherent)

Good point. And this actually diminishes the value of using the version as documentation: v1, v2 and v3 themes could use patterns, but that setting would only work in the WordPress 6.0 runtime or above.

Let's try to address the documentation concerns in a different way: de-emphasize version and focus on documenting which setting works in a given runtime.