Add theme.json v1 reference and v1 to v2 migration docs #37886
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Size Change: +148 B (0%) Total Size: 1.13 MB
ℹ️ View Unchanged
|
ajlende
added
the
Global Styles
ajlende
force-pushed
the
add/theme-json-v2-migration-docs
branch
2 times, most recently
from
ff438cd to
034a5a3
Compare
oandregal
reviewed
Jan 12, 2022
| @@ -559,10 +559,28 @@ | |||
| }, | |||
| { | |||
| "title": "Theme.json Reference", | |||
| "slug": "theme-json-reference", | |||
There was a problem hiding this comment.
We may need to keep this slug as theme-json-reference as there's an existing theme-json slug here.
There was a problem hiding this comment.
@oandregal This would be /reference-guides/theme-json, so I assumed it would be okay. But I forgot to do a search for existing links which I'll take care of now
There was a problem hiding this comment.
Do you know if there's a way to redirect the old URL to the new one? I don't like that organizing the related docs into a folder will break the existing links
There was a problem hiding this comment.
This would be /reference-guides/theme-json, so I assumed it would be okay. But I forgot to do a search for existing links which I'll take care of now
I'm not sure how it works, to be honest.
Do you know if there's a way to redirect the old URL to the new one? I don't like that organizing the related docs into a folder will break the existing links
Yeah, that's feasible. In the past, we had to do this and it involved creating a track ticket for meta, for example https://meta.trac.wordpress.org/ticket/4388 In general, it's best to avoid asking for redirections too frequently as they are a small team. If we can go with the existing, it's going to be quicker to land this PR.
There was a problem hiding this comment.
As for the slug names, what do you think of having:
theme-json-referencefor top-level (ortheme-jsonplus setting up a redirection for the old slug: either to this top-level page or to the "living" page below).migrationsfor the migrations doc, so it becomes https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/migrations/v1(alternativelytheme-json-v1) for the v1 doc, so it becomes https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/v1/living(alternativelyunstable, etc) for the "latest" doc, so it's clear that it can change, and it becomes https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/living/
Thinking out loud: when the time comes to freeze the v2 we have to extract the living to a v2 doc that will be manually curated from then on. We could even add a notice in the top-level of this doc explaining this and linking to the latest stable doc.
There was a problem hiding this comment.
The rest of the names changes seem good to me. I'll get those changes pushed up here soon and ask in #meta on slack to see if they know about using the same slug nested differently. (slack link)
There was a problem hiding this comment.
Also asked in #docs and it sounds like we probably can't reuse a slug which leaves the question: are we okay with https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/ changing to the new ToC page instead of redirecting it to the living reference like it was before?
There was a problem hiding this comment.
Seeing as we can't reuse slugs, we probably want something more specific than living, v1, and migrations.
EDIT:
I pushed c12ebed477a0db5fb92625d1b84d3ee9408f5b73 to rename the paths as:
.../theme-json-reference/.../theme-json-reference/theme-json-unstable/.../theme-json-reference/theme-json-v1/.../theme-json-reference/theme-json-migrations/
The question above about redirection still stands.
There was a problem hiding this comment.
are we okay with https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/ changing to the new ToC page instead of redirecting it to the living reference like it was before?
I think this should be fine.
There was a problem hiding this comment.
I see we use "living" in some places and "unstable" in others (file names, titles, etc). Would you mind consolidating everything to "living"?
Just a personal preference. Now that I see "unstable" it sounds less than ideal, as the theme.json is "stable" in that it works, just it can change. If you feel strongly either way (or any other option), go for it. As long as we use the same name everywhere we're fine.
oandregal
reviewed
Jan 12, 2022
oandregal
reviewed
Jan 12, 2022
oandregal
reviewed
Jan 12, 2022
oandregal
reviewed
Jan 12, 2022
oandregal
reviewed
Jan 12, 2022
oandregal
reviewed
Jan 12, 2022
|
@oandregal I opened #37925 to update the v1 schema in wp/5.8 to match the changes you made here. |
ajlende
force-pushed
the
add/theme-json-v2-migration-docs
branch
from
ef84f73 to
cf2558a
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Alternative to #37772
Having separate docs pages for different versions of the schema has some benefits.
The drawbacks are in maintaining these docs.