Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DO NOT MERGE] POC - use docusaurus's recommended "next/latest" versioning practice #910

Closed

Conversation

pepopowitz
Copy link
Collaborator

@pepopowitz pepopowitz commented May 17, 2022

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:

image

In the dropdown, I have an option for "Next":

image

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:

image

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.

@pepopowitz
Copy link
Collaborator Author

Closing this as it's for POC purposes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

1 participant