[DO NOT MERGE] POC - use docusaurus's recommended "next/latest" versioning practice #910
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.
This PR will not be merged.
This is a proof of concept on abandoning our current versioning practice of presenting the "latest" version as default and un-numbered, in favor of docusaurus's recommendation of presenting the last numbered version as default, and the "next" version as unstable.
Why?
In relation to #906, this versioning approach would allow us to iteratively work toward moving an entire section of the docs (or multiple sections) into a second docs instance.
With our current versioning approach, we can't make any changes without affecting a "live" version -- either an older numbered version, or the "latest" version. This means we'd need a very-large-and-long-lived PR to move sections around, to avoid incomplete work prematurely surfacing to users.
With the approach in this PR, we can make changes against the "next" version iteratively. When a user browses the "current" version, it'll be the most recent numbered version. If they want to poke around the "next" version, they can, but they will see a message that they're not viewing docs for the current version.
Demo
https://www.loom.com/share/f790432e6d7842cf8859c1552a4769a1
Some screenshots
When I view the main docs without specifying a version, Docusaurus treats it as if I'm viewing the last tagged version:
In the dropdown, I have an option for "Next":
And after I pick it, I'm viewing the "next" version of the docs, including a message that it's not the current versionhttps://www.loom.com/share/f790432e6d7842cf8859c1552a4769a1:
Other work not shown in this PR
If we do make this switch, we'd need to cut a new version of the docs using
npm run docusaurus docs:version .... This is a pretty trivial step, but just capturing it here for completeness.I don't think there'd be any redirects or content link updates associated with this work. Users would still see the latest version of docs at the same URLs...they would just be presented in the UI with a specified version.