Add proposal for GEPs

.github/ISSUE_TEMPLATE/enhancement.md

@@ -9,3 +9,8 @@ labels: kind/feature
 **What would you like to be added**:
 
 **Why is this needed**:
+
+NOTE: depending on the scope of the enhancement, you may be asked to use the
+GEP process to document your work:
+
+https://gateway-api.sigs.k8s.io/contributing/gep/

site-src/contributing/enhancement-requests.md

@@ -1,34 +1,41 @@
 # Enhancement Tracking and Backlog
 
-Inspired by [Kubernetes enhancements](https://github.com/kubernetes/enhancements), service-api's
-provides a process for introducing new functionality or considerable changes to the project. The
+Inspired by [Kubernetes enhancements][enhance], Gateway API provides a process for
+introducing new functionality or considerable changes to the project. The
 enhancement process will evolve over time as the project matures.
 
-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.
+[enhance]: https://github.com/kubernetes/enhancements
+
+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](https://github.com/kubernetes-sigs/gateway-api/issues/new/choose) and select
-"Enhancement Request".
-2. Follow the instructions in the enhancement request template and submit the Issue.
+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]: /contributing/gep.md
 
 ## What is Considered an Enhancement?
 
 An enhancement is generally anything that:
 
-- impacts how a cluster is operated including addition or removal of significant
-  capabilities
-- introduces changes to an api
-- needs significant effort to implement
-- requires documentation to utilize
+- Introduces changes to an API.
+- Needs significant effort to implement.
+- Requires documentation to utilize.
+- Impacts how a system is operated including addition or removal of significant
+  capabilities.
 
 It is unlikely to require an enhancement if it:
 
-- fixes a bug
-- adds more testing
-- code refactors
-- minimal impact to a release
+- Fixes a bug
+- Adds more testing
+- Code refactors
 
 If you're unsure the proposed work requires an enhancement, file an issue
 and ask.
@@ -37,23 +44,22 @@ and ask.
 
 Create an enhancement once you have:
 
-- circulated your idea to see if there is interest.
-- identified community members who agree to work on and maintain the enhancement.
-- enhancements may take several releases to complete.
-- a prototype in your own fork (optional)
-
+- Circulated your idea to see if there is interest.
+- Identified community members who agree to work on and maintain the enhancement.
+- Enhancements may take several releases to complete.
+- A prototype in your own fork (optional)
 
 ## Why are Enhancements Tracked
 
-As the project evolves, it's important that the service-api's community understands
-how the enhancement affects the project.  Individually, it's hard to understand how
-all parts of the system interact, but as a community we can work together to build
+As the project evolves, it's important that the community understands how the
+enhancement affects the project.  Individually, it's hard to understand how all
+parts of the system interact, but as a community we can work together to build
 the right design and approach before getting too deep into an implementation.
 
 ## When to Comment on an Enhancement Issue
 
 Please comment on the enhancement issue to:
 
-- request a review or clarification on the process
-- update status of the enhancement effort
-- link to relevant issues in other repos
+- Request a review or clarification on the process
+- Update status of the enhancement effort
+- Link to relevant issues in other repos

site-src/contributing/gep.md

@@ -0,0 +1,115 @@
+# Gateway Enhancement Proposal (GEP)
+
+Gateway Enhancement Proposals (GEPs) will serve a similar purpose to
+the [KEP][kep] process for the main Kubernetes project:
+
+1. Ensure that changes to the API follow a known process and discussion
+  in the OSS community.
+1. Make changes and proposals discoverable (current and future).
+1. Document design ideas, tradeoffs, decisions that were made for
+  historical reference.
+
+As this is still a relatively new project, we don't wish to encumber
+proposals with a large amount of boilerplate process. The most
+important part of the GEP are the last two items: making sure that we
+can easily find previous discussions and alternatives considered.
+
+## Process
+
+### New GEP
+
+* File an issue that will be used to track the GEP progress. Use the existing
+  issue templates. Use this number for naming the GEP (i.e. issue #123 would be
+  named `gep-123.md`).
+* Discussion and comments occur on the issue and shared docs. Any
+  relevant shared documents should be linked off of the Github issue.
+  * Create a GEP document in `site-srcs/gep/gep-<issue
+    #>-short-description.md` with status `proposed`; the sections that
+    MUST be kept up to date are `TLDR` and `References`. Other
+    sections can refer to the issue or shared doc temporarily.
+  * We should try to resolve most of the discussion in this phase as doing the
+    discussion on a GEP is not very easy (at the moment) from a workflow
+    perspective.
+* When there is consensus on the approach, consolidate any content,
+  links into the document (see template format below). Submit the
+  PR for merging.
+* Propagate iterations on the GEP proposal from the issue/shared docs
+  to the GEP.
+* When there are no further comments, update GEP with status
+  "accepted". This means that we are committing to implementing/have
+  implemented the feature.
+  * Make sure any shared docs are going to be in a format that is accessible in
+    the future. If possible, copy the contents of the document into the GEP
+    along with comments.
+* Set the GEP status (accepted, implemented etc).
+* Tracking issue should be marked as closed.
+
+## Format
+
+``` markdown
+# GEP-1234: Add Chaosnet protocol support
+
+Status: (provisional, implementable, implemented, deferred, rejected, withdrawn, or replaced)
+
+(See definitions in: https://github.com/kubernetes/enhancements/blob/master/keps/NNNN-kep-template/kep.yaml#L9)
+
+## TLDR
+
+(1-2 sentence summary of the proposal)
+
+## Motivation/User Journeys/Background
+
+(Can link to external doc -- but we should bias towards copying
+the content into the GEP as online documents are easier to lose
+-- e.g. owner messes up the permissions, accidental deletion)
+
+## API
+
+(... details, can point to PR with changes)
+
+
+## Alternatives
+
+(List other design alternatives and why we did not go in that
+direction)
+
+## Out of scope
+
+(What is out of scope for this proposal.)
+
+## References
+
+(Add any additional document links. Again, we should try to avoid
+too much content not in version control to avoid broken links)
+```
+
+## Out of scope
+
+What is out of scope: see [text from KEP][kep-when-to-use]. Examples:
+
+* Bug fixes
+* Small changes (API validation, documentation, fixups). It always
+  possible that the reviewers will determine a "small" change ends up
+  requiring a GEP.
+
+## How much additional work is this?
+
+* Need to copy out material into a `.md` document for future
+  reference and keep it up to date.
+* Need to keep GEP up to date with current references to shared doc.
+* Some amount of overhead merging GEPs into the repo.
+
+## FAQ
+
+* Q: Why is it named GEP?
+  * A: To avoid potential confusion if people start following the cross
+    references to the full KEP process.
+* Q: Why have a different process than mainline?
+  * A: We would like to keep the machinery to an absolute minimum for now --
+    this will likely change as we move to v1.
+* Q: Is it ok to discuss using shared docs, scratch docs etc?
+  * A: Yes! We view GEPs as primarily historical record to ensure that any
+    artifacts are preserved for future discussions.
+
+[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/geps/gep-696.md

@@ -0,0 +1,37 @@
+# GEP-684: GEP template
+
+* Issue URL: https://github.com/kubernetes-sigs/gateway-api/pull/684
+* Status: (provisional, implementable, implemented, deferred, rejected, withdrawn, or replaced)
+
+(See definitions in [Kubernetes KEP][kep-status].
+
+[kep-status]: https://github.com/kubernetes/enhancements/blob/master/keps/NNNN-kep-template/kep.yaml#L9
+
+## TLDR
+
+(1-2 sentence summary of the proposal)
+
+## Motivation/User Journeys/Background
+
+(Can link to external doc -- but we should bias towards copying
+the content into the GEP as online documents are easier to lose
+-- e.g. owner messes up the permissions, accidental deletion)
+
+## API
+
+(... details, can point to PR with changes)
+
+
+## Alternatives
+
+(List other design alternatives and why we did not go in that
+direction)
+
+## Out of scope
+
+(What is out of scope for this proposal.)
+
+## References
+
+(Add any additional document links. Again, we should try to avoid
+too much content not in version control to avoid broken links)

site-src/v1alpha2/contributing/enhancement-requests.md

@@ -1,34 +1,41 @@
 # Enhancement Tracking and Backlog
 
-Inspired by [Kubernetes enhancements](https://github.com/kubernetes/enhancements), service-api's
-provides a process for introducing new functionality or considerable changes to the project. The
+Inspired by [Kubernetes enhancements][enhance], Gateway API provides a process for
+introducing new functionality or considerable changes to the project. The
 enhancement process will evolve over time as the project matures.
 
-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.
+[enhance]: https://github.com/kubernetes/enhancements
+
+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](https://github.com/kubernetes-sigs/gateway-api/issues/new/choose) and select
-"Enhancement Request".
-2. Follow the instructions in the enhancement request template and submit the Issue.
+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]: /contributing/gep
 
 ## What is Considered an Enhancement?
 
 An enhancement is generally anything that:
 
-- impacts how a cluster is operated including addition or removal of significant
-  capabilities
-- introduces changes to an api
-- needs significant effort to implement
-- requires documentation to utilize
+- Introduces changes to an API.
+- Needs significant effort to implement.
+- Requires documentation to utilize.
+- Impacts how a system is operated including addition or removal of significant
+  capabilities.
 
 It is unlikely to require an enhancement if it:
 
-- fixes a bug
-- adds more testing
-- code refactors
-- minimal impact to a release
+- Fixes a bug
+- Adds more testing
+- Code refactors
 
 If you're unsure the proposed work requires an enhancement, file an issue
 and ask.
@@ -37,23 +44,22 @@ and ask.
 
 Create an enhancement once you have:
 
-- circulated your idea to see if there is interest.
-- identified community members who agree to work on and maintain the enhancement.
-- enhancements may take several releases to complete.
-- a prototype in your own fork (optional)
-
+- Circulated your idea to see if there is interest.
+- Identified community members who agree to work on and maintain the enhancement.
+- Enhancements may take several releases to complete.
+- A prototype in your own fork (optional)
 
 ## Why are Enhancements Tracked
 
-As the project evolves, it's important that the service-api's community understands
-how the enhancement affects the project.  Individually, it's hard to understand how
-all parts of the system interact, but as a community we can work together to build
+As the project evolves, it's important that the community understands how the
+enhancement affects the project.  Individually, it's hard to understand how all
+parts of the system interact, but as a community we can work together to build
 the right design and approach before getting too deep into an implementation.
 
 ## When to Comment on an Enhancement Issue
 
 Please comment on the enhancement issue to:
 
-- request a review or clarification on the process
-- update status of the enhancement effort
-- link to relevant issues in other repos
+- Request a review or clarification on the process
+- Update status of the enhancement effort
+- Link to relevant issues in other repos