Skip to content

Latest commit

 

History

History
115 lines (84 loc) · 4.11 KB

gep.md

File metadata and controls

115 lines (84 loc) · 4.11 KB
Raw

Gateway Enhancement Proposal (GEP)

Gateway Enhancement Proposals (GEPs) will serve a similar purpose to the KEP process for the main Kubernetes project:

  1. Ensure that changes to the API follow a known process and discussion in the OSS community.
  2. Make changes and proposals discoverable (current and future).
  3. 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

# 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. 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.