[Feature request]: Allow multiple versions

[tuxmea]

Use Case

With OpenVox 9 coming soon, we need to find a solution on having documentation for multiple versions.

Describe the solution you would like

Having the possibility to select the version on the website.
Versions differ between OpenVox, OpenFact and OpenBolt.

Describe alternatives you've considered

No response

Additional context

No response

[miharp]

Proposed approach for multi-version docs (#320) — looking for a gut-check before we build anything

With OpenVox 9 coming, here's the model I'd like to propose. It's deliberately simple and builds on how the site already works.

Versioned directories on one branch — no version branches

When a product cuts a new major, we copy its current docs into a new versioned directory and freeze the old one:

docs/_openvox_8x/   →   add docs/_openvox_9x/

master stays the single publishing branch. New work happens in the newest version; older versions only get deliberate backports for important fixes. This avoids long-lived release branches and the constant rebasing/backporting that comes with them.

Stable, per-product URLs with a per-product latest

/openvox/8.x/   /openvox/9.x/   /openvox/latest/
/openfact/5.x/                  /openfact/latest/
/openbolt/5.x/                  /openbolt/latest/

Each product versions independently — /openvox/latest/ could be 9.x while /openfact/latest/ is still 5.x.

Generated reference docs are pinned per version

So historical docs stay historical: OpenVox 8.x docs build from the OpenVox 8 source, 9.x from 9, etc. — rather than always regenerating from the newest tag.

A version selector in the UI

Probably at the top of the sidebar. It shows only the current product's versions and tries to keep you on the same page when you switch:

OpenVox:  latest | 9.x | 8.x

The ask

Does this general direction work for everyone? Specifically —

• Comfortable with directories-on-one-branch vs. release branches?
• OK treating each product's versioning independently?
• Anything about your product (OpenFact / OpenBolt / Server) that wouldn't fit this shape?

If the direction has support, I'll follow up with a concrete implementation plan.

[tuxmea]

I agree to the concept.
This is what we had from scratch and I am OK to continue that path.

At the moment cross section links use latest within paths.
We need to rename the affected links to stay at the same version.

General question: should we use versioned links instead of latest in general.

Another question which I brought to the monthly:

We have content unrelated to versions and we have the autogenerated content.
Some version unrelated content might change over time.
Should we link static content files instead of copying?

[tuxmea]

At the moment we filter prereleases. see https://github.com/OpenVoxProject/openvox-docs/blob/master/lib/puppet_references/repo.rb#L50 We need a different solution prior the first final 9.0.0 release is tagged

[binford2k]

my concern remains that bookmarks and google search links, etc. will often point to old versions.

This concern could be alleviated by ensuring that EVERY frozen legacy page gets a prominent "this page is out of date, click here for the current version" notice pinned to the page viewport so it doesn't scroll out of sight.

Note that this approach will require the 404 page to have a "search for the missing page" functionality or we'll never be able to rename pages.

[miharp]

Update on the out-of-date-pages concern in this thread:

• Add pinned out-of-date banner and /latest/ canonicals for versioned docs #437 adds the pinned notice @binford2k asked for: every page of a frozen (non-latest) version gets a banner pinned to the bottom of the viewport linking to the product's /latest/ docs. Coverage is derived from _data/products.yml, so the moment a product's latest moves, all pages of its older collections get the banner automatically — no per-page changes. The same PR canonicalizes the numbered/latest duplicate pair (e.g. /openvox/8.x/... → /openvox/latest/...) so search engines index the stable /latest/ URLs, which works on the "Google links point at old versions" problem from the search side too.
• 404 page should offer search for the missing page #438 tracks the companion piece, 404-page search — the stated precondition for ever renaming pages. Until that exists, the banner deliberately links to the product's /latest/ root rather than the same page under /latest/, since a renamed page would 404.