Phasing out Beta from Versioning Guide

robscott · robscott · commit b8b134ac9e23 · 2023-09-29T02:11:49.000Z
diff --git a/geps/gep-922.md b/geps/gep-922.md
@@ -3,19 +3,24 @@
 * Issue: [#922](https://github.com/kubernetes-sigs/gateway-api/issues/922)
 * Status: Standard
 
+!!! note
+    Although this GEP serves as a reference for how we developed the Gateway API
+    versioning model, it is not meant to be the current source of truth.
+    Instead, please refer to our [official Versioning
+    Policy](/concepts/versioning) for the most up-to-date guidelines.
+
 ## TLDR
 Each Gateway API release will be represented by a bundle version that represents
 that specific combination of CRDs, API versions, and validating webhook. To
 enable experimental fields, future releases of the API will include standard and
 experimental CRD tracks. Users will be able to access experimental features by
 installing the experimental CRDs. A cluster can contain either an experimental
-or standard CRD for any resource at a given time. 
-
+or standard CRD for any resource at a given time.
 
 ## Goals
 Provide a path for implementations to support:
 
-* Users should have a predictable experience when interacting with Gateway API. 
+* Users should have a predictable experience when interacting with Gateway API.
 * The API should be able to continue to safely evolve, including:
     * Loosening validation
     * Transitioning required fields to optional
@@ -123,7 +128,7 @@ recommended for production use.
 
 If experimental fields are removed or renamed, the original field name should be
 removed from the go struct, with a tombstone comment ensuring the field name
-will not be reused. 
+will not be reused.
 
 Each CRD will be published with annotations that indicate their bundle version
 and channel:
@@ -146,7 +151,7 @@ messy.
 
 ### 2: Reuse Alpha API versions
 With this approach, we would only allow the use of these fields when using the
-alpha API. 
+alpha API.
 
 To simplify conversion, new fields will be added to all versions of the API,
 with some key exceptions:
diff --git a/site-src/concepts/versioning.md b/site-src/concepts/versioning.md
@@ -2,59 +2,87 @@
 
 ## Overview
 Each new release of Gateway API is defined with a "bundle version" that
-represents the Git tag of a release, such as v0.4.0. This contains the
+represents the Git tag of a release, such as v0.8.0. This contains the
 following:
 
 * API Types (Go bindings for the resources)
 * CRDs (Kubernetes definitions of the resources)
-* Validating Webhook
-
-### API Versions (e.g. v1alpha2, v1beta1)
-Within Gateway API, API versions are primarily used to indicate the stability of
-a resource. For example, if a resource has not yet graduated to beta, it is
-still possible that it could either be removed from the API or changed in
-backwards incompatible ways. For more information on API versions, refer to the
-[full Kubernetes API versioning
-documentation](https://kubernetes.io/docs/reference/using-api/#api-versioning).
-
-![Lifecycle of New Gateway API Resources](/images/lifecycle-new-resources.png)
-<!-- Source: https://docs.google.com/presentation/d/1sfZTV-vlisDUIie_iK_B2HqKia_querT6m6T2_vbAk0/edit -->
-
-### Release Channels (e.g. Experimental, Standard)
-Gateway API provides 2 release channels: an Experimental one and a Standard one.
+* Validating Webhook (Will be deprecated in v1.0 release)
+
+### Release Channels
+Release channels are used to indicate feature stability within Gateway API. All
+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.
+
+The following diagram provides a high level overview of the lifecycle of a
+feature or resource proposed by a new [GEP](/geps/overview/) (enhancement
+proposal) in Gateway API:
+
+```mermaid
+flowchart TD
+    0([Implementable GEP]) --> 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
+
+style A fill:#eeb
+style C fill:#beb
+style F fill:#ebb
+```
 
 The Standard release channel includes:
 
-* Resources that have graduated to beta
-* All fields that have graduated to standard and are no longer considered
-  experimental
+* Resources that have graduated to Beta or GA API Versions
+* All fields that have graduated to Standard from the Experimental channel
 
 The Experimental release channel includes everything in the Standard release
 channel, plus:
 
-* Alpha API resources
-* New fields that are considered experimental and have not yet graduated to the
-  standard channel
+* Resources with Alpha API Versions
+* All new fields before they graduate to Standard channel
 
 ![Release Channel Overlap](/images/release-channel-overlap.svg)
 <!-- Source: https://docs.google.com/presentation/d/1sfZTV-vlisDUIie_iK_B2HqKia_querT6m6T2_vbAk0/edit -->
 
-Release channels are used to indicate feature stability within Gateway API. For
-example, even if a resource has already graduated to beta, we need a way to test
-out new fields and features before committing to their long term stability. With
-upstream Kubernetes APIs, this is accomplished with [feature
-gates](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/).
-Unfortunately, CRDs do not have a similar concept yet.
-
-Instead of trying to recreate feature gates in this project, we've introduced
-release channels. Starting in v0.5.0, all new fields and features will start in
-the Experimental release channel. From that point, these may graduate to the
-Standard release channel or be dropped from the API entirely. See
-[GEP-922](/geps/gep-922) for a more detailed discussion of this approach to new
-fields and features.
-
-![Lifecycle of New Gateway API Fields](/images/lifecycle-new-fields.svg)
-<!-- Source: https://docs.google.com/presentation/d/1sfZTV-vlisDUIie_iK_B2HqKia_querT6m6T2_vbAk0/edit -->
+We recommend using the "Standard" release channel by default as it will provide
+a stable experience. The "Experimental" feature enables us to iterate on new
+features quickly but may include breaking changes and should not be relied on
+in production environments.
+
+### 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
+stability, expressed by our release channels as described above.
+
+In general, this means that when resources graduate from the Experimental
+channel to the Standard channel, they'll also be graduating from an Alpha API
+Version (v1alpha2) to a GA API Version (v1).
+
+#### Beta
+Some resources have already graduated to the Standard API Channel with a Beta
+API Version (v1beta1):
+
+* HTTPRoute
+* Gateway
+* GatewayClass
+* ReferenceGrant
+
+In the upcoming v1.0 release, HTTPRoute, Gateway, and GatewayClass will all
+graduate to a GA API Version (v1). All future resources that graduate to
+Standard channel will include a v1 API version as part of that process.
+
+ReferenceGrant is a special case since it is in the process of [transitioning
+into an upstream Kubernetes
+API](https://github.com/kubernetes/enhancements/issues/3766) that is owned by
+[sig-auth](https://github.com/kubernetes/community/blob/master/sig-auth/README.md).
+Until that is resolved, it is likely that ReferenceGrant will be effectively
+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.
 
 ## Version Indicators
 Each CRD will be published with annotations that indicate their bundle version
@@ -67,74 +95,61 @@ gateway.networking.k8s.io/channel: standard|experimental
 
 ## What can Change
 When using or implementing this API, it is important to understand what can
-change across API versions.
+change across bundle versions.
 
 ### Patch version (e.g. v0.4.0 -> v0.4.1)
-* Clarifications to godocs
-* Updates to CRDs and/or code to fix a bug
-* Conformance test fixes
-* Additional conformance test coverage for existing features
-* Fixes to typos
+* API Spec:
+    * Clarifications
+    * Correcting typos
+* Bug fixes:
+    * Correcting validation
+    * Fixes to release process or artifacts
+* Conformance tests:
+    * Fixes for existing tests
+    * Additional conformance test coverage for existing features
 
 ### Minor version (e.g. v0.4.0 -> v0.5.0)
 * Everything that is valid in a patch release
-* New experimental API fields or resources
-* Changes to recommended conditions or reasons in status
-* Loosened validation
-* Making required fields optional
-* Removal of experimental fields
-* Removal of experimental resources
-* Graduation of fields or resources from experimental to standard track
-* Changes to conformance tests to match spec updates
-* Introduction of a new **API version**, which may also include:
-  * Renamed fields
-  * Anything else that is valid in a new Kubernetes API version
-  * Removal/tombstoning of beta fields
-* Removal of an API resource following [Kubernetes deprecation
+* Experimental Channel:
+    * Adding new API fields or resources
+    * Breaking changes for existing API fields or resources
+    * Removing API fields or resources without prior deprecation
+* Standard Channel:
+    * Graduation of fields or resources from Experimental to Standard Channel
+    * Removal of an API resource following [Kubernetes deprecation
   policy](https://kubernetes.io/docs/reference/using-api/deprecation-policy/)
+* All Channels:
+    * Changes to recommended conditions or reasons in status
+    * Loosened validation (including making required fields optional)
+    * Changes to conformance tests to match spec updates
+    * Introduction of a new API version which may include renamed fields or
+      anything else that is valid in a [new Kubernetes API
+      version](https://kubernetes.io/docs/reference/using-api/#api-versioning)
 
 ### Major version (e.g. v0.x to v1.0)
 * There are no API compatibility guarantees when the major version changes.
 
 ## Graduation Criteria
+For a resource, field, or feature to graduate from Experimental to Standard, it
+must meet the following criteria:
 
-### Resources
-
-#### Alpha -> Beta
-A resource to graduate from alpha to beta must meet the following criteria:
-
-* Implemented by several implementations.
-* Conformance test framework is in place, with some coverage of basic
-  functionality.
-* Validation is well thought out.
-* Most of the API surface is being exercised by users.
-* Approval from subproject owners + KEP reviewers.
-
-#### Beta -> GA
-
-A resource to graduate from beta to GA must meet the following criteria:
-
-* Almost all of the fields and behavior have conformance test coverage.
+* Full conformance test coverage.
 * Multiple conformant implementations.
 * Widespread implementation and usage.
-* At least 6 months of soak time as a beta API.
+* At least 6 months of soak time as an alpha API.
+* No significant changes for at least 1 minor release and 3 months
 * Approval from subproject owners + KEP reviewers.
 
-### Fields
-
-#### Experimental -> Standard
-As described above, field level stability is layered on top of beta and GA
-resources (no fields in alpha resources can be considered standard). The
-requirements for a field to graduate from experimental to standard depend on the
-API version of the resource it is a part of. For a field to be considered
-standard, it needs to meet the same criteria of the resource it is contained in.
+## Supported Versions
+This project aims to provide support for a wide range of Kubernetes versions with
+consistent upgrade experiences across versions. To accomplish that, we commit to:
 
-If a resource has graduated to beta, an experimental field must meet all of the
-beta graduation criteria before graduating to standard. Similarly, if a resource
-has graduated to GA, a field must meet all of the beta and GA graduation
-criteria. There is one slight variation here, instead of 6 months of soak time
-as a beta API, a field graduating to standard requires 6 months of soak time as an
-experimental field.
+1. Support a minimum of the most recent 5 Kubernetes minor versions.
+2. Ensure that all standard channel changes between v1beta1 and v1 are fully
+   compatible and convertible.
+3. Take every possible effort to avoid introduction of a conversion webhook. If
+   a conversion webhook needs to be introduced, it will be supported for the
+   lifetime of the API, or at least until an alternative is available.
 
 ## Out of Scope
 ### Unreleased APIs
@@ -148,15 +163,3 @@ this project.
 We do not provide stability guarantees for source code imports. The Interfaces
 and behavior may change in an unexpected and backwards-incompatible way in any
 future release.
-
-## Supported Versions
-
-This project aims to provide support for a wide range of Kubernetes versions with
-consistent upgrade experiences across versions. To accomplish that, we commit to:
-
-1. Support a minimum of the most recent 5 Kubernetes minor versions.
-2. Ensure that all standard channel changes between v1beta1 and v1 are fully
-   compatible and convertible.
-3. Take every possible effort to avoid introduction of a conversion webhook. If
-   a conversion webhook needs to be introduced, it will be supported for the
-   lifetime of the API, or at least until an alternative is available.
