1# Gateway Enhancement Proposal (GEP)
2
3Gateway Enhancement Proposals (GEPs) serve a similar purpose to the [KEP][kep]
4process for the main Kubernetes project:
5
61. Ensure that changes to the API follow a known process and discussion
7 in the OSS community.
81. Make changes and proposals discoverable (current and future).
91. Document design ideas, tradeoffs, decisions that were made for
10 historical reference.
11
12## Process
13
14This 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
19flowchart 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
34Before creating a GEP, share your high level idea with the community. There are
35several 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
41Please default to GitHub discussions: they work a lot like GitHub issues which
42makes 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.
46At this point, you should copy the outcome of any other conversations or documents
47into this document.
48
49### 3. Agree on the Goals
50Although it can be tempting to start writing out all the details of your
51proposal, it's important to first ensure we all agree on the goals. The first
52version of your GEP should aim for a "Provisional" status and leave out any
53implementation details, focusing primarily on "Goals" and "Non-Goals".
54
55### 3. Document Implementation Details
56Now that everyone agrees on the goals, it is time to start writing out your
57proposed implementation details. These implementation details should be very
58thorough, including the proposed API spec, and covering any relevant edge cases.
59Note that it may be helpful to use a shared doc for part of this phase to enable
60faster iteration on potential designs.
61
62It is likely that throughout this process, you will discuss a variety of
63alternatives. Be sure to document all of these in the GEP, and why we decided
64against them. At this stage, the GEP should be targeting the "Implementable"
65stage.
66
67### 4. Implement the GEP as "Experimental"
68
69With the GEP marked as "Implementable", it is time to actually make those
70proposed changes in our API. In some cases, these changes will be documentation
71only, but in most cases, some API changes will also be required. It is important
72that every new feature of the API is marked as "Experimental" when it is
73introduced. Within the API, we use `<gateway:experimental>` tags to denote
74experimental fields. Within Golang packages (conformance tests, CLIs, e.t.c.) we
75use the `experimental` Golang build tag to denote experimental functionality.
76
77Some 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
83Before changes are released they MUST be documented. GEPs that have not been
84both implemented and documented before a release cut off will be excluded from
85the release.
86
87#### Probationary Period
88
89Any GEP in the `Experimental` phase is automatically under a "probationary
90period" where it will come up for re-assessment if its graduation criteria are
91not met within a given time period. GEPs that wish to move into `Experimental`
92status MUST document a proposed period (6 months is the suggested default) that
93MUST be approved by maintainers. Maintainers MAY select an alternative time
94duration for a probationary period if deemed appropriate, and will document
95their 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
101At the end of a probationary period if the GEP has not been able to resolve
102its graduation criteria it will move to "Rejected" status. In extenuating
103circumstances an extension of that period may be accepted by approval from
104maintainers. GEPs which are `Rejected` in this way are removed from the
105experimental CRDs and more or less put on hold. GEPs may be allowed to move back
106into `Experimental` status from `Rejected` for another probationary period if a
107new strategy for achieving their graduation criteria can be established. Any
108such plan to take a GEP "off the shelf" must be reviewed and accepted by the
109maintainers.
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
117Once this feature has met the [graduation criteria](/concepts/versioning/#graduation-criteria), it is
118time to graduate it to the "Standard" channel of the API. Depending on the feature, this may include
119any of the following:
120
1211. Graduating the resource to beta
1222. Graduating fields to "standard" by removing `<gateway:experimental>` tags
1233. Graduating a concept to "standard" by updating documentation
124
125### 6. Close out the GEP issue
126
127The 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
132In short, the GEP issue should only be closed when the work is "done" (whatever
133that means for that GEP).
134
135## Status
136
137Each GEP has a status field that defines it's current state. Each transition
138will require a PR to update the GEP and should be discussed at a community
139meeting 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
156Although 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
169GEPs should match the format of the template found in [GEP-696](/geps/gep-696).
170
171## Out of scope
172
173What 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
View as plain text