[Docs] Adopt Versioning

[robscott]

What would you like to be added:
Adopting some form of versioning for documentation would enable us to review and merge docs for a feature before it is released. This may just be versioned branches, or selectively versioning sections of the website. Unfortunately different areas of our website could use different approaches to versioning:

Area	Goal
Implementations	Always Latest
Conformance Results/Tables	Likely want to wait one month after a release before displaying latest, also want to be able to show historical results
GEPs	Likely want to who latest status for ease of reference, but this could get confusing as GEP status on website may not match released status
Features + Guides	Should match release
API Spec	Should match release
Contributing	Always Latest

Some potential options:

1. Reuse release branches
With this approach, we'd pin the docs website to the latest release-1.x branch. Every fix, update, and GEP would need to be cherry picked to that branch. Future-looking updates would go straight to main.

2. Introduce new docs branches
As part of a release process, we'd create a docs branch reserved for future releases, and send unreleased updates directly to that. I don't think this would allow us to avoid unreleased updates to the API spec documentation though.

3. Introduce selective versioning for some subset of the website
Instead of using branches, we could duplicate sections of our website that would benefit from versioning, and continue to serve everything from main.

Why this is needed:
In #3108, we have a feature that has met all graduation criteria for standard channel in v1.2, but we don't really have a good place to put the corresponding docs updates before v1.2 is formally released. This is just one of many examples of a common pain point when documenting features in Gateway API.

[youngnick]

I think that 1 is pretty unavoidable - although moving to Hugo instead of mkdocs would allow us to use the same tooling as upstream Kubernetes, which may make getting contributors easier. That's a big job though.

[xtineskim]

for displaying conformance results, is there consensus on wanting it to be 1 month post release, or the suggested wait till 3 implementations are submitted (comment)?

[robscott]

for displaying conformance results, is there consensus on wanting it to be 1 month post release, or the suggested wait till 3 implementations are submitted (comment)?

Maybe instead of "whichever comes first", we should say "whichever comes later", so we can ensure that implementations always have at least 1 month to implement the latest release of an API to be included in our conformance table.

[youngnick]

Agreed, I like "one month after release, or whenever three implementations support it, whichever is longer" as the rule.

[guicassolato]

Prior art: docs.kuadrant.io uses mkdocs as well and it has versioned docs.

I think it's based on https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning IIRC.

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle stale
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle rotten
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten