Plan and implement documentation/website versioning

[petejohanson]

Need to plan and implement a versioning system for our documentation. In particular, as we have more major release versions, with breaking changes, it would be helpful for users to see version specific docs as needed.

Some discussed solutions:

• Netlify deploys for our version branches as well. Some searching indicates the "best" (only) way to do this is to change our Netlify deployment settings to deploy all branches, and then use a ignore command to ignore everything but main and our version.
• Use docusaurus versioning to do this. Advantage is keeping it all deploying together, easy drop down for users to pick the version they want to read, etc. Cons: Duplication, larger repo size, potentially higher long term maintenance burden.

I don't have a strong opinion one way or another, and would appreciate thoughts from others.

[caksoylar]

I think I am leaning towards the former just to avoid code duplication and increased maintenance. Maybe we can solve the UX issue by adding a dropdown to the top bar manually, with fixed URLs for available versions?

For old versions, we could have a link to go to "latest release", "main" (which can be constant URLs) and for the latest release/main, we could include manually added links to older version branches. Not as nice as being able to go to any version from any page, but avoids updating old version docs to point to newer versions.

Also, I wonder if that would let us version only docs/docs, and not blog and other top level projects? It doesn't seem possible if it is branch-based, so that might be a point against it. For instance, we might want to have the same changelog on all version docs.

[Nick-Munnich]

Looking at the docusaurus notes on versioning, they have this point. Based on that, my suggestion would be to use their suggested archiving function of netlify, and use docusaurus versioning for the most recent release, main/dev, and any LTS versions that we are actively supporting. That does have some code duplication, but it doesn't involve any maintenance beyond what we should be maintaining anyway.

[petejohanson]

Summary of some discussion on Discord:

• Our merged release-please automation also pushes a version branch, e.g. v0.1-branch
• Update netlify setup with setting to deploy all branches, and add an ignore script that only deploys branches matching main or our version pattern.
• Update netlify configuration to deploy all branches, and leverage ignore script to keep the actual deploys to a minimum.
• Use Docusaurus "Archived" links to link to previous version deployments.