sigs.k8s.io/gateway-api@v1.0.0/geps/overview.md (about)

     1  # Gateway Enhancement Proposal (GEP)
     2  
     3  Gateway Enhancement Proposals (GEPs) serve a similar purpose to the [KEP][kep]
     4  process for the main Kubernetes project:
     5  
     6  1. Ensure that changes to the API follow a known process and discussion
     7    in the OSS community.
     8  1. Make changes and proposals discoverable (current and future).
     9  1. Document design ideas, tradeoffs, decisions that were made for
    10    historical reference.
    11  
    12  ## Process
    13  
    14  This diagram shows the state diagram of the GEP process at a high level, but the details are below.
    15  
    16  <div align="center">
    17    
    18  ```mermaid
    19  flowchart TD
    20      D([Discuss with<br />the community]) --> C
    21      C([Issue Created]) --> Provisional
    22      Provisional -->|GEP Doc PR<br />done| Implementable
    23      Provisional -->|If practical <br /> work needed| Prototyping
    24      Prototyping -->|GEP Doc PR<br />done| Implementable
    25      Implementable -->|Gateway API<br />work completed| Experimental
    26      Experimental -->|Supported in<br />multiple implementations<br />+ Conformance tests| Standard
    27      Standard -->|Entire change is GA or implemented| Completed
    28  ```
    29  
    30  </div>
    31  
    32  ### 1. Discuss with the community
    33  
    34  Before creating a GEP, share your high level idea with the community. There are
    35  several places this may be done:
    36  
    37  - A [new GitHub Discussion](https://github.com/kubernetes-sigs/gateway-api/discussions/new)
    38  - On our [Slack Channel](https://kubernetes.slack.com/archives/CR0H13KGA)
    39  - On one of our [community meetings](https://gateway-api.sigs.k8s.io/contributing/?h=meetings#meetings)
    40  
    41  Please default to GitHub discussions: they work a lot like GitHub issues which
    42  makes them easy to search.
    43  
    44  ### 2. Create an Issue
    45  [Create a GEP issue](https://github.com/kubernetes-sigs/gateway-api/issues/new?assignees=&labels=kind%2Ffeature&template=enhancement.md) in the repo describing your change.
    46  At this point, you should copy the outcome of any other conversations or documents
    47  into this document.
    48  
    49  ### 3. Agree on the Goals
    50  Although it can be tempting to start writing out all the details of your
    51  proposal, it's important to first ensure we all agree on the goals. The first
    52  version of your GEP should aim for a "Provisional" status and leave out any
    53  implementation details, focusing primarily on "Goals" and "Non-Goals".
    54  
    55  ### 3. Document Implementation Details
    56  Now that everyone agrees on the goals, it is time to start writing out your
    57  proposed implementation details. These implementation details should be very
    58  thorough, including the proposed API spec, and covering any relevant edge cases.
    59  Note that it may be helpful to use a shared doc for part of this phase to enable
    60  faster iteration on potential designs.
    61  
    62  It is likely that throughout this process, you will discuss a variety of
    63  alternatives. Be sure to document all of these in the GEP, and why we decided
    64  against them. At this stage, the GEP should be targeting the "Implementable"
    65  stage.
    66  
    67  ### 4. Implement the GEP as "Experimental"
    68  
    69  With the GEP marked as "Implementable", it is time to actually make those
    70  proposed changes in our API. In some cases, these changes will be documentation
    71  only, but in most cases, some API changes will also be required. It is important
    72  that every new feature of the API is marked as "Experimental" when it is
    73  introduced. Within the API, we use `<gateway:experimental>` tags to denote
    74  experimental fields. Within Golang packages (conformance tests, CLIs, e.t.c.) we
    75  use the `experimental` Golang build tag to denote experimental functionality.
    76  
    77  Some other requirements must be met before marking a GEP `Experimental`:
    78  
    79  - the graduation criteria to reach `Standard` MUST be filled out
    80  - a proposed probationary period (see next section) must be included in the GEP
    81    and approved by maintainers.
    82  
    83  Before changes are released they MUST be documented. GEPs that have not been
    84  both implemented and documented before a release cut off will be excluded from
    85  the release.
    86  
    87  #### Probationary Period
    88  
    89  Any GEP in the `Experimental` phase is automatically under a "probationary
    90  period" where it will come up for re-assessment if its graduation criteria are
    91  not met within a given time period. GEPs that wish to move into `Experimental`
    92  status MUST document a proposed period (6 months is the suggested default) that
    93  MUST be approved by maintainers. Maintainers MAY select an alternative time
    94  duration for a probationary period if deemed appropriate, and will document
    95  their reasoning.
    96  
    97  > **Rationale**: This probationary period exists to avoid GEPs getting "stale"
    98  > and to provide guidance to implementations about how relevant features should
    99  > be used, given that they are not guaranteed to become supported.
   100  
   101  At the end of a probationary period if the GEP has not been able to resolve
   102  its graduation criteria it will move to "Rejected" status. In extenuating
   103  circumstances an extension of that period may be accepted by approval from
   104  maintainers. GEPs which are `Rejected` in this way are removed from the
   105  experimental CRDs and more or less put on hold. GEPs may be allowed to move back
   106  into `Experimental` status from `Rejected` for another probationary period if a
   107  new strategy for achieving their graduation criteria can be established. Any
   108  such plan to take a GEP "off the shelf" must be reviewed and accepted by the
   109  maintainers.
   110  
   111  > **Warning**: It is extremely important** that projects which implement
   112  > `Experimental` features clearly document that these features may be removed in
   113  > future releases.
   114  
   115  ### 5. Graduate the GEP to "Standard"
   116  
   117  Once this feature has met the [graduation criteria](/concepts/versioning/#graduation-criteria), it is
   118  time to graduate it to the "Standard" channel of the API. Depending on the feature, this may include
   119  any of the following:
   120  
   121  1. Graduating the resource to beta
   122  2. Graduating fields to "standard" by removing `<gateway:experimental>` tags
   123  3. Graduating a concept to "standard" by updating documentation
   124  
   125  ### 6. Close out the GEP issue
   126  
   127  The GEP issue should only be closed once the feature has:
   128  - Moved to the standard channel for distribution (if necessary)
   129  - Moved to a "v1" `apiVersion` for CRDs
   130  - been completely implemented and has wide acceptance (for process changes).
   131  
   132  In short, the GEP issue should only be closed when the work is "done" (whatever
   133  that means for that GEP).
   134  
   135  ## Status
   136  
   137  Each GEP has a status field that defines it's current state. Each transition
   138  will require a PR to update the GEP and should be discussed at a community
   139  meeting before merging. Most GEPS will proceed through the following states:
   140  
   141  * **Provisional:** The goals described by this GEP have consensus but
   142    implementation details have not been agreed to yet.
   143  * **Prototyping:** An extension of `Provisional` which can be opted in to in
   144    order to indicate to the community that there are some active practical tests
   145    and experiments going on which are intended to be a part of the development
   146    of this GEP. This may include APIs or code, but that content _must_ not be
   147    distributed with releases.
   148  * **Implementable:** The goals and implementation details described by this GEP
   149    have consensus but have not been fully implemented yet.
   150  * **Experimental:** This GEP has been implemented and is part of the
   151    "Experimental" release channel. Breaking changes are still possible, up to
   152    and including complete removal and moving to `Rejected`.
   153  * **Standard:** This GEP has been implemented and is part of the
   154    "Standard" release channel. It should be quite stable.
   155  
   156  Although less common, some GEPs may end up in one of the following states:
   157  
   158  * **Deferred:** We do not currently have bandwidth to handle this GEP, it
   159    may be revisited in the future.
   160  * **Rejected:** This proposal was considered by the community but ultimately
   161    rejected.
   162  * **Replaced:** This proposal was considered by the community but ultimately
   163    replaced by a newer proposal.
   164  * **Withdrawn:** This proposal was considered by the community but ultimately
   165    withdrawn by the author.
   166  
   167  ## Format
   168  
   169  GEPs should match the format of the template found in [GEP-696](/geps/gep-696).
   170  
   171  ## Out of scope
   172  
   173  What is out of scope: see [text from KEP][kep-when-to-use]. Examples:
   174  
   175  * Bug fixes
   176  * Small changes (API validation, documentation, fixups). It is always
   177    possible that the reviewers will determine a "small" change ends up
   178    requiring a GEP.
   179  
   180  ## FAQ
   181  
   182  * Q: Why is it named GEP?
   183    * A: To avoid potential confusion if people start following the cross
   184      references to the full KEP process.
   185  * Q: Why have a different process than mainline?
   186    * A: We would like to keep the machinery to an absolute minimum for now --
   187      this may change as we move to v1.
   188  * Q: Is it ok to discuss using shared docs, scratch docs etc?
   189    * A: Yes, this can be a helpful intermediate step when iterating on design
   190      details. It is important that all major feedback, discussions, and
   191      alternatives considered in that step are represented in the GEP though. A
   192      key goal of GEPs is to show why we made a decision and which alternatives
   193      were considered. If separate docs are used, it's important that we can
   194      still see all relevant context and decisions in the final GEP.
   195  * Q: When should I mark a GEP as `Prototyping` as opposed to `Provisional`?
   196    * A: The `Prototyping` status carries the same base meaning as `Provisional`
   197      in that consensus is not complete between stakeholders and we're not ready
   198      to move toward releasing content yet. You should use `Prototyping` to
   199      indicate to your fellow community members that we're in a state of active
   200      practical tests and experiments which are intended to help us learn and
   201      iterate on the GEP. These can include distributing content, but not under
   202      any release channel.
   203  * Q: Should I implement support for `Experimental` channel features?
   204    * A: Ultimately one of the main ways to get something into `Standard` is for
   205      it to mature through the `Experimental` phase, so we really _need_ people
   206      to implement these features and provide feedback in order to have progress.
   207      That said, the graduation of a feature past `Experimental` is not a forgone
   208      conclusion. Before implementing an experimental feature, you should:
   209  
   210      * Clearly document that support for the feature is experimental and may disappear in the future.
   211      * Have a plan in place for how you would handle the removal of this feature from the API.
   212  
   213  [kep]: https://github.com/kubernetes/enhancements
   214  [kep-when-to-use]: https://github.com/kubernetes/enhancements/tree/master/keps#do-i-have-to-use-the-kep-process