-
Notifications
You must be signed in to change notification settings - Fork 465
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Initial enhancement proposal template #10539
Changes from all commits
d7bcb5e
a8e9902
558aca4
0c9495c
a81e792
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,153 @@ | ||
<!-- | ||
**Note:** When your Enhancement Proposal (EP) is complete, all of these comment blocks should be removed. | ||
|
||
This template is inspired by the Kubernetes Enhancement Proposal (KEP) template: https://github.com/kubernetes/enhancements/blob/master/keps/sig-architecture/0000-kep-process/README.md | ||
|
||
To get started with this template: | ||
|
||
- [ ] **Create an issue in kgateway-dev/kgateway** | ||
- [ ] **Make a copy of this template.** | ||
`EP-[ID]: [Feature/Enhancement Name]`, where `ID` is the issue number (with no | ||
leading-zero padding) assigned to your enhancement above. | ||
- [ ] **Fill out this file as best you can.** | ||
At minimum, you should fill in the "Summary" and "Motivation" sections. | ||
- [ ] **Create a PR for this EP.** | ||
Assign it to maintainers with relevant context. | ||
- [ ] **Merge early and iterate.** | ||
Avoid getting hung up on specific details and instead aim to get the goals of | ||
the EP clarified and merged quickly. The best way to do this is to just | ||
start with the high-level sections and fill out details incrementally in | ||
subsequent PRs. | ||
|
||
Just because a EP is merged does not mean it is complete or approved. Any EP | ||
marked as `provisional` is a working document and subject to change. You can | ||
denote sections that are under active debate as follows: | ||
|
||
``` | ||
<<[UNRESOLVED optional short context or usernames ]>> | ||
Stuff that is being argued. | ||
<<[/UNRESOLVED]>> | ||
``` | ||
|
||
When editing EPS, aim for tightly-scoped, single-topic PRs to keep discussions | ||
focused. If you disagree with what is already in a document, open a new PR | ||
with suggested changes. | ||
|
||
One EP corresponds to one "feature" or "enhancement" for its whole lifecycle. Once a feature has become | ||
"implemented", major changes should get new EPs. | ||
--> | ||
# EP-[ID]: [Feature/Enhancement Name] | ||
|
||
<!-- | ||
This is the title of your EP. Keep it short, simple, and descriptive. A good | ||
title can help communicate what the EP is and should be considered as part of | ||
any review. | ||
--> | ||
|
||
* Issue: [#ID](URL to GitHub issue) | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. do we want to keep these issues open as the enhancement graduates from alpha -> beta -> stable (like KEPs), or close them once implemented? if so, should we add something about the current stage / graduation criteria in this template (maybe that's getting ahead of ourselves) There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I don't think we need specific stages, but that's a good question on when an EP can be closed out. I think for now though the issue should be closed out when the code merges, and then any larger follow-ups require their own EP. |
||
|
||
<!-- | ||
A table of contents is helpful for quickly jumping to sections of a EP and for | ||
highlighting any additional information provided beyond the standard EP | ||
template. | ||
|
||
Ensure the TOC is wrapped with | ||
<code><!-- toc --&rt;<!-- /toc --&rt;</code> | ||
tags, and then generate with `hack/update-toc.sh`. | ||
--> | ||
|
||
## Background | ||
|
||
<!-- | ||
Provide a brief overview of the feature/enhancement, including relevant background information, origin, and sponsors. | ||
Highlight the primary purpose and how it fits within the broader ecosystem. | ||
|
||
Include Motivation, concise overview of goals, challenges, and trade-offs. | ||
|
||
--> | ||
|
||
## Motivation | ||
|
||
<!-- | ||
This section is for explicitly listing the motivation, goals, and non-goals of | ||
this EP. Describe why the change is important and the benefits to users. The | ||
motivation section can optionally provide links to [experience reports] to | ||
demonstrate the interest in a EP within the wider Kubernetes community. | ||
|
||
[experience reports]: https://github.com/golang/go/wiki/ExperienceReports | ||
--> | ||
|
||
### Goals | ||
|
||
<!-- | ||
|
||
List the specific goals of the EP. What is it trying to achieve? How will we | ||
know that this has succeeded? | ||
|
||
Include specific, actionable outcomes. Ensure that the goals focus on the scope of | ||
the proposed feature. | ||
--> | ||
|
||
|
||
### Non-Goals | ||
|
||
<!-- | ||
What is out of scope for this EP? Listing non-goals helps to focus discussion | ||
and make progress. | ||
--> | ||
|
||
## Implementation Details | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. If I was introducing a new CRD or some extension of an API (e.g. aggregated webhook), would I outline that within the implementation details section or a dedicated API section? |
||
|
||
<!-- | ||
This section should contain enough information that the specifics of your | ||
change are understandable. This may include API specs (though not always | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. how should we handle API/design/implementation updates, would this design doc need to be kept up to date whenever those change? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think significant API, design, or implementation changes should have a dedicated EP linked to a specific issue, which is closed once the code merges. There are two cases:
|
||
required) or even code snippets. If there's any ambiguity about HOW your | ||
proposal will be implemented, this is the place to discuss them. | ||
|
||
|
||
### Configuration | ||
Specify changes to any configuration APIs, CRDs, or user-facing options to enable/disable | ||
the feature. Include references to relevant files or configurations that need updates. | ||
|
||
### Plugin | ||
Describe how the feature will be added as a plugin (if applicable). | ||
Include references to existing plugin frameworks or structures. | ||
Highlight the plugin's responsibilities and integration points. | ||
|
||
### Controllers | ||
Outline the responsibilities of new or updated controllers. | ||
Specify conditions for their operation and integration with existing resources. | ||
Mention required RBAC updates or new permissions. | ||
|
||
### Deployer | ||
Detail deployment-specific updates, e.g., Helm chart modifications, custom deployer changes, etc. | ||
Include any prerequisites or dependencies for deployment. | ||
|
||
### Translator and Proxy Syncer | ||
Specify updates to translators, syncers, or other intermediary components. | ||
Highlight how these components interact with the feature's resources or backend. | ||
|
||
### Reporting | ||
Describe changes to status reporting or monitoring frameworks. | ||
Include any caveats or limitations in initial reporting. | ||
--> | ||
|
||
### Test Plan | ||
|
||
<!-- | ||
Define the testing strategy for the feature. | ||
Include unit, integration, and end-to-end (e2e) tests. | ||
Specify any additional frameworks or tools required for testing. | ||
--> | ||
|
||
## Alternatives | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. What happens if there's a legitimate alternative worth exploring further? Create another design doc and link back here? Add a sub-section under this alternative with a lengthy amount of context/description? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Yep! I think you could link other EPs here or have a length discussion section. Really depends on the feature! |
||
|
||
<!-- | ||
Highlight potential challenges or trade-offs. | ||
--> | ||
|
||
## Open Questions | ||
|
||
<!-- | ||
Include any unresolved questions or areas requiring feedback. | ||
--> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
maybe worth mentioning what possible states the EP can be in (provisional, implemented, etc?), and how you mark it as 'provisional' (maybe we need another doc for that)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hm, good call- maybe I should remove the "provisional" section? The EP has two stages:
Maybe this should be a label/field on the issue itself?