From 413b8f72252d1f284a88277b174f29db04adcd0a Mon Sep 17 00:00:00 2001 From: Bexx Date: Wed, 3 Dec 2025 09:00:45 -0800 Subject: [PATCH 1/3] Update versioning docs to reflect recent changes in release process. --- site-src/concepts/versioning.md | 63 +++++++++++++++++++++++++++++++-- 1 file changed, 61 insertions(+), 2 deletions(-) diff --git a/site-src/concepts/versioning.md b/site-src/concepts/versioning.md index b3b9f0ce75..cc3803ed72 100644 --- a/site-src/concepts/versioning.md +++ b/site-src/concepts/versioning.md @@ -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. + 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: @@ -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 @@ -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: From 064998f90944a51ea3a39b8c0954a518393323a2 Mon Sep 17 00:00:00 2001 From: Beka Modebadze Date: Fri, 12 Dec 2025 11:53:41 -0800 Subject: [PATCH 2/3] Removed extra details about release requirements. --- site-src/concepts/versioning.md | 19 +++++-------------- 1 file changed, 5 insertions(+), 14 deletions(-) diff --git a/site-src/concepts/versioning.md b/site-src/concepts/versioning.md index cc3803ed72..7ba714b966 100644 --- a/site-src/concepts/versioning.md +++ b/site-src/concepts/versioning.md @@ -14,17 +14,8 @@ 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. +We have introduced new requirements for each level change, and these +requirements can be viewed at this [thread](https://github.com/kubernetes-sigs/gateway-api/discussions/4164) 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 @@ -73,10 +64,10 @@ 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 +* **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 +* **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 From 996a7c289cf70a361366fa79c0af88c53d06994a Mon Sep 17 00:00:00 2001 From: Beka Modebadze Date: Fri, 12 Dec 2025 12:39:13 -0800 Subject: [PATCH 3/3] Removed link for new releases. --- site-src/concepts/versioning.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/site-src/concepts/versioning.md b/site-src/concepts/versioning.md index 7ba714b966..cee5f79686 100644 --- a/site-src/concepts/versioning.md +++ b/site-src/concepts/versioning.md @@ -14,9 +14,6 @@ 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. -We have introduced new requirements for each level change, and these -requirements can be viewed at this [thread](https://github.com/kubernetes-sigs/gateway-api/discussions/4164) - 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: