Skip to content

[Docs] Adopt Versioning #3115

@robscott

Description

@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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    kind/documentationCategorizes issue or PR as related to documentation.lifecycle/rottenDenotes an issue or PR that has aged beyond stale and will be auto-closed.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions