Skip to content

Update versioning docs to reflect recent changes in the release process. #4308

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bexxmodd wants to merge 3 commits into
base: main
Choose a base branch
from
+49 −2
Open

Update versioning docs to reflect recent changes in the release process. #4308

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
413b8f7
Update versioning docs to reflect recent changes in release process.
bexxmodd Dec 3, 2025
064998f
Removed extra details about release requirements.
bexxmodd Dec 12, 2025
996a7c2
Removed link for new releases.
bexxmodd Dec 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 49 additions & 2 deletions site-src/concepts/versioning.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,17 +20,21 @@ proposal) in Gateway API:

```mermaid
flowchart TD
0([Implementable GEP]) --> A
0([Provisional GEP]) --> 1([Sponsors Committed])
1 --> 2([Implementable GEP])
2 --> A
A>Experimental Channel] --> B([Widely used and working well?])
B -->|Yes| C>Standard Channel]
B -->|No| D([Could Changes Help?])
D -->|Yes| E([Adjust and try again])
D -->|No| F>Remove From API]
E -->A

2 -->|No progress in 6 months| G([Auto-dropped])
Copy link
Member

@robscott robscott Dec 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this should go from experimental channel instead of provisional. IMO it's fine for ideas to sit in "provisional" indefinitely, but as soon as they become part of the API surface, they need to either move forward or get dropped so we're not stuck with an alpha API that's treated as stable simply because it's existed a long time.

Copy link
Contributor

@kflynn kflynn Dec 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm good with this, too, after double-checking the diagram. 🙂


style A fill:#eeb
style C fill:#beb
style F fill:#ebb
style G fill:#ebb
```

The Standard release channel includes:
Expand All @@ -54,6 +58,15 @@ Channel which enables us to iterate on new features quickly. Note that this
channel makes no backwards compatibility guarantees and breaking changes may be
released at any point.

#### Validating Admission Policies (VAP)
Gateway API uses Validating Admission Policies to protect channel boundaries:

* **Upgrade VAP**: Prevents applying experimental-channel CRDs over
standard-channel CRDs. If you need to do this, you'll have to remove this VAP.
* **Guardrails VAP**: Prevents setting any experimental fields of a resource
unless an annotation is also present. Without the annotation, you get
standard-channel functionality only.

### API Versions
Upstream Kubernetes APIs have 3 levels of stability, denoted by alpha, beta, and
GA API versions. In Gateway API, we've narrowed this down to 2 levels of
Expand Down Expand Up @@ -99,6 +112,40 @@ frozen as beta in Gateway API. When it is widely available as a built-in
Kubernetes API, we will likely remove it from the Standard Channel of Gateway
API.

## Release Process

### Standard Channel Releases
Standard-channel releases follow a date-based cadence. The release date is
Copy link
Member

@robscott robscott Dec 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@kflynn @youngnick @rikatz Are we OK about being more prescriptive here, such as "we target a 4 month cadence for standard channel releases"?

Copy link
Contributor

@kflynn kflynn Dec 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@robscott I'm fine with that.

chosen in advance and will not slip; however, the content is flexible. Whatever
content is ready to go at the release date will ship; content that isn't ready
will wait for the next release. The release number is ideally chosen at the
point when its content is known.

### Monthly Experimental Releases
Copy link
Member

@robscott robscott Dec 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bexxmodd @kflynn one detail I'm not clear about - will we have a "monthly" release in the same month we have a standard channel release? I'm assuming the answer is no, or that the standard channel release counts for that month, but would be good to clarify.

Copy link
Contributor Author

@bexxmodd bexxmodd Dec 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO we still should release monthly, as it allows to try out experimental features without requiring them to consume new release.

Copy link
Contributor

@kflynn kflynn Dec 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with @bexxmodd – so next February, we should have both a monthly-2026.02 and a proper semver release, and in fact those two releases should have identical content at the API level (which implies that we tag the monthly, then cut the fledging semver release branch from commit we just tagged as the monthly). Knowing that there's a monthly every month just seems simpler.

Gateway API publishes monthly releases of the Experimental channel, tagged as
`monthly-$year-$month` (e.g., `monthly-2025-11`). These releases:

* Only include `experimental-install.yaml`
* Are not allowed to change the Standard channel
* Are snapshots of the main branch
* Do not receive backports of bugfixes (upgrade to a newer monthly instead)
* Do not use SemVer release numbers, as breaking changes to experimental
resources and fields are always allowed between monthlies

The purpose of monthly releases is to enable faster iteration in the
Experimental channel.

### SemVer Releases
Copy link
Member

@robscott robscott Dec 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we need to be careful here. We use "semantic versioning terminology", but we also include breaking changes in minor releases (thanks to experimental channel), and therefore aren't strictly following semantic versioning. Kubernetes upstream is pretty careful how it words this: https://kubernetes.io/releases/version-skew-policy/#supported-versions. I think we should go further and say that semantic versioning concepts only apply to how we structure versions, but that we have a broader set of acceptable changes in any given release (https://gateway-api.sigs.k8s.io/concepts/versioning/#what-can-change).

Copy link
Contributor

@kflynn kflynn Dec 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@robscott Want to make a suggestion for this text?

Gateway API continues to publish SemVer releases (e.g., `1.5.0`, `1.6.0`) on a
regular cadence. These releases:

* Include both `experimental-install.yaml` and `standard-install.yaml`
* Are not snapshots of main: they have release branches to allow for backporting
bugfixes
* Most likely, the `experimental-install.yaml` in a SemVer release will be
identical to the one contained in the monthly release right before it, though
that's not required

## Version Indicators
Each CRD will be published with annotations that indicate their bundle version
and channel:
Expand Down