Merge pull request #2097 from shaneutt/shaneutt/gep-probation

docs: add probationary step to Experimental GEP phase

Author: k8s-ci-robot

geps/gep-1016.md

@@ -3,6 +3,12 @@
 * Issue: [#1016](https://github.com/kubernetes-sigs/gateway-api/issues/1016)
 * Status: Experimental
 
+> **Note**: This GEP is exempt from the [Probationary Period][expprob] rules of
+> our GEP overview as it existed before those rules did, and so it has been
+> explicitly grandfathered in.
+
+[expprob]:https://gateway-api.sigs.k8s.io/geps/overview/#probationary-period
+
 ## Goal
 
 Add an idiomatic GRPCRoute for routing gRPC traffic.

geps/gep-1323.md

@@ -3,6 +3,12 @@
 * Issue: [#1323](https://github.com/kubernetes-sigs/gateway-api/issues/1323)
 * Status: Experimental
 
+> **Note**: This GEP is exempt from the [Probationary Period][expprob] rules of
+> our GEP overview as it existed before those rules did, and so it has been
+> explicitly grandfathered in.
+
+[expprob]:https://gateway-api.sigs.k8s.io/geps/overview/#probationary-period
+
 ## TLDR
 Similar to how we have `RequestHeaderModifier` in `HTTPRouteFilter`, which lets users modify request headers before the request is forwarded to a backend (or a group of backends), it’d be helpful to have a `ResponseHeaderModifier` field which would let users modify response headers before they are returned to the client.
 

geps/gep-1748.md

@@ -3,6 +3,12 @@
 * Issue: [#1748](https://github.com/kubernetes-sigs/gateway-api/issues/1748)
 * Status: Experimental
 
+> **Note**: This GEP is exempt from the [Probationary Period][expprob] rules of
+> our GEP overview as it existed before those rules did, and so it has been
+> explicitly grandfathered in.
+
+[expprob]:https://gateway-api.sigs.k8s.io/geps/overview/#probationary-period
+
 ## TLDR
 
 The Kubernetes Multi-Cluster Services API enables Services to span multiple

geps/gep-713.md

@@ -3,6 +3,12 @@
 * Issue: [#713](https://github.com/kubernetes-sigs/gateway-api/issues/713)
 * Status: Experimental
 
+> **Note**: This GEP is exempt from the [Probationary Period][expprob] rules of
+> our GEP overview as it existed before those rules did, and so it has been
+> explicitly grandfathered in.
+
+[expprob]:https://gateway-api.sigs.k8s.io/geps/overview/#probationary-period
+
 ## TLDR
 
 This GEP aims to standardize terminology and processes around using one Kubernetes

geps/gep-957.md

@@ -3,6 +3,12 @@
 * Issue: [#957](https://github.com/kubernetes-sigs/gateway-api/issues/957)
 * Status: Experimental
 
+> **Note**: This GEP is exempt from the [Probationary Period][expprob] rules of
+> our GEP overview as it existed before those rules did, and so it has been
+> explicitly grandfathered in.
+
+[expprob]:https://gateway-api.sigs.k8s.io/geps/overview/#probationary-period
+
 ## TLDR
 
 Add a new `port` field to ParentRef to support port matching in Routes.

geps/overview.md

@@ -65,18 +65,54 @@ against them. At this stage, the GEP should be targeting the "Implementable"
 stage.
 
 ### 4. Implement the GEP as "Experimental"
+
 With the GEP marked as "Implementable", it is time to actually make those
 proposed changes in our API. In some cases, these changes will be documentation
 only, but in most cases, some API changes will also be required. It is important
 that every new feature of the API is marked as "Experimental" when it is
 introduced. Within the API, we use `<gateway:experimental>` tags to denote
 experimental fields.
 
-Before these changes are released, they will also need to be documented.
-GEPs that have not been both implemented and documented before a release
-cut off will be excluded from the release.
+Some other requirements must be met before marking a GEP `Experimental`:
+
+- the graduation criteria to reach `Standard` MUST be filled out
+- a proposed probationary period (see next section) must be included in the GEP
+  and approved by maintainers.
+
+Before changes are released they MUST be documented. GEPs that have not been
+both implemented and documented before a release cut off will be excluded from
+the release.
+
+#### Probationary Period
+
+Any GEP in the `Experimental` phase is automatically under a "probationary
+period" where it will come up for re-assessment if its graduation criteria are
+not met within a given time period. GEPs that wish to move into `Experimental`
+status MUST document a proposed period (6 months is the suggested default) that
+MUST be approved by maintainers. Maintainers MAY select an alternative time
+duration for a probationary period if deemed appropriate, and will document
+their reasoning.
+
+> **Rationale**: This probationary period exists to avoid GEPs getting "stale"
+> and to provide guidance to implementations about how relevant features should
+> be used, given that they are not guaranteed to become supported.
+
+At the end of a probationary period if the GEP has not been able to resolve
+its graduation criteria it will move to "Rejected" status. In extenuating
+circumstances an extension of that period may be accepted by approval from
+maintainers. GEPs which are `Rejected` in this way are removed from the
+experimental CRDs and more or less put on hold. GEPs may be allowed to move back
+into `Experimental` status from `Rejected` for another probationary period if a
+new strategy for achieving their graduation criteria can be established. Any
+such plan to take a GEP "off the shelf" must be reviewed and accepted by the
+maintainers.
+
+> **Warning**: It is extremely important** that projects which implement
+> `Experimental` features clearly document that these features may be removed in
+> future releases.
 
 ### 5. Graduate the GEP to "Standard"
+
 Once this feature has met the [graduation criteria](/concepts/versioning/#graduation-criteria), it is
 time to graduate it to the "Standard" channel of the API. Depending on the feature, this may include
 any of the following:
@@ -111,7 +147,8 @@ meeting before merging. Most GEPS will proceed through the following states:
 * **Implementable:** The goals and implementation details described by this GEP
   have consensus but have not been fully implemented yet.
 * **Experimental:** This GEP has been implemented and is part of the
-  "Experimental" release channel. Breaking changes are still possible.
+  "Experimental" release channel. Breaking changes are still possible, up to
+  and including complete removal and moving to `Rejected`.
 * **Standard:** This GEP has been implemented and is part of the
   "Standard" release channel. It should be quite stable.
 
@@ -162,6 +199,15 @@ What is out of scope: see [text from KEP][kep-when-to-use]. Examples:
     practical tests and experiments which are intended to help us learn and
     iterate on the GEP. These can include distributing content, but not under
     any release channel.
+* Q: Should I implement support for `Experimental` channel features?
+  * A: Ultimately one of the main ways to get something into `Standard` is for
+    it to mature through the `Experimental` phase, so we really _need_ people
+    to implement these features and provide feedback in order to have progress.
+    That said, the graduation of a feature past `Experimental` is not a forgone
+    conclusion. Before implementing an experimental feature, you should:
+
+    * Clearly document that support for the feature is experimental and may disappear in the future.
+    * Have a plan in place for how you would handle the removal of this feature from the API.
 
 [kep]: https://github.com/kubernetes/enhancements
 [kep-when-to-use]: https://github.com/kubernetes/enhancements/tree/master/keps#do-i-have-to-use-the-kep-process

site-src/concepts/conformance.md

@@ -13,8 +13,8 @@ Within Gateway API, release channels are used to indicate the stability of a
 field or resource. The "standard" channel of the API includes fields and
 resources that have graduated to "beta". The "experimental" channel of the API
 includes everything in the "standard" channel, along with experimental fields
-and resources that may still be changed in breaking ways or removed altogether.
-For more information on this concept, refer to our
+and resources that may still be changed in breaking ways **or removed
+altogether**. For more information on this concept, refer to our
 [versioning](/concepts/versioning) documentation.
 
 ## 2. Support Levels

site-src/contributing/enhancement-requests.md

@@ -10,17 +10,6 @@ Enhancements provides the basis of a community roadmap. Enhancements may be
 filed by anyone, but require approval from a maintainer to accept the
 enhancement into the project.
 
-## Quick start
-
-1. Create an [Issue][issue] and select "Enhancement Request".
-2. Follow the instructions in the enhancement request template and submit the
-   Issue.
-3. (depending on size of change) Start a [draft Gateway Enhancement Proposal
-   (GEP)][gep]
-
-[issue]: https://github.com/kubernetes-sigs/gateway-api/issues/new/choose
-[gep]: /geps/overview
-
 ## What is Considered an Enhancement?
 
 An enhancement is generally anything that:
@@ -49,6 +38,20 @@ Create an enhancement once you have:
 - Enhancements may take several releases to complete.
 - A prototype in your own fork (optional)
 
+## How to Create a New Enhancement
+
+Once you've circulated your idea and received feedback from the maintainers
+that creating a [Gateway Enhancement Proposal (GEP)][gep] is a good next step:
+
+- create an [Issue][issue] and select "Enhancement Request"
+- follow the instructions in the enhancement request template and submit the
+  Issue.
+- create an initial pull request to add your GEP. Follow the directions in the
+  [GEP documentation][gep].
+
+[issue]: https://github.com/kubernetes-sigs/gateway-api/issues/new/choose
+[gep]: /geps/overview
+
 ## Why are Enhancements Tracked
 
 As the project evolves, it's important that the community understands how the