kubernetes-sigs
[Docs] Adopt Versioning
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 https://github.com/kubernetes-sigs/gateway-api/pull/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.
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.
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)?
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.
Agreed, I like "one month after release, or whenever three implementations support it, whichever is longer" as the rule.
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.
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/staleis applied - After 30d of inactivity since
lifecycle/stalewas applied,lifecycle/rottenis applied - After 30d of inactivity since
lifecycle/rottenwas 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
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/staleis applied - After 30d of inactivity since
lifecycle/stalewas applied,lifecycle/rottenis applied - After 30d of inactivity since
lifecycle/rottenwas 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
The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.
This bot triages issues according to the following rules:
- After 90d of inactivity,
lifecycle/staleis applied - After 30d of inactivity since
lifecycle/stalewas applied,lifecycle/rottenis applied - After 30d of inactivity since
lifecycle/rottenwas applied, the issue is closed
You can:
- Reopen this issue with
/reopen - Mark this issue as fresh with
/remove-lifecycle rotten - Offer to help out with Issue Triage
Please send feedback to sig-contributor-experience at kubernetes/community.
/close not-planned
@k8s-triage-robot: Closing this issue, marking it as "Not Planned".
In response to this:
The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.
This bot triages issues according to the following rules:
- After 90d of inactivity,
lifecycle/staleis applied- After 30d of inactivity since
lifecycle/stalewas applied,lifecycle/rottenis applied- After 30d of inactivity since
lifecycle/rottenwas applied, the issue is closedYou can:
- Reopen this issue with
/reopen- Mark this issue as fresh with
/remove-lifecycle rotten- Offer to help out with Issue Triage
Please send feedback to sig-contributor-experience at kubernetes/community.
/close not-planned
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.
