Skip to content
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

Merged
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
153 changes: 153 additions & 0 deletions docs/content/enhancements/template.md
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
Copy link
Contributor

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)

Copy link
Contributor Author

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:

  1. provisional (has not been fully implemented yet)
  2. implemented (code has merged, EP is up to date to reflect the state)

Maybe this should be a label/field on the issue itself?

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)
Copy link
Contributor

Choose a reason for hiding this comment

The 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)

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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>&lt;!-- toc --&rt;&lt;!-- /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
Copy link
Member

Choose a reason for hiding this comment

The 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
Copy link
Contributor

Choose a reason for hiding this comment

The 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?

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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:

  1. If code changes affect the API/design during the implementation stage, the EP must be updated. Before merging the final PR or closing the issue, the EP should reflect the latest state.
  2. If there are changes that need to be made after the code merges, a new EP/issue needs to be created. This can reference the old issue, but the original EP should remain unchanged.

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
Copy link
Member

Choose a reason for hiding this comment

The 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?

Copy link
Contributor Author

Choose a reason for hiding this comment

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