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 1 commit into
base: main
Choose a base branch
from
+61 −2
Open

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
63 changes: 61 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 @@ -14,23 +14,39 @@ new features and resources start in the Experimental release channel. From that
point, these may graduate to the Standard release channel or be dropped from the
API entirely.

To get a new item into the Experimental channel, you need:
* A Who/What/Why [GEP](../geps/overview.md) merged as Provisional
* Implementations willing to sponsor the item by agreeing to implement it as an
experimental feature
* Items affecting north-south aspects of Gateway API require three sponsors
* Items affecting only east-west aspects require two sponsors

The GEP can be merged into Provisional before soliciting sponsors. Once an item
moves from Provisional to Implementable, it will be automatically dropped if it
doesn't make any significant progress in six months. This process is handled
with a public review, typically at the first meeting of every month.
Comment on lines +17 to +27
Copy link
Contributor

@youngnick youngnick Dec 5, 2025

Choose a reason for hiding this comment

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

I'm worried that this will go stale - any chance we could put something like "There are requirements for each level change, and those are documented at ". That way, if we update the GEP overview doc with the process, we don't need to update it here as well.


The following diagram provides a high level overview of the lifecycle of a
feature or resource proposed by a new [GEP](../geps/overview.md) (enhancement
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])

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 +70,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 +124,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
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
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
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
Loading