Initial enhancement proposal template #10539
Conversation
| --> | ||
|
|
||
| <!-- toc --> | ||
| - [Background](#Background) |
There was a problem hiding this comment.
Looks like the background link is broken -- at least when I look at the markdown preview tab in the UI.
There was a problem hiding this comment.
Also, do we want a table of contents of proposals? I always felt it was overkill in the KEP format and we could slim down while still following the high-level sections (e.g. background, motivation, goals / non-goals) without being too boggle down on a heavy format.
There was a problem hiding this comment.
Yeah fair, there are only a couple sections in the template if we remove the implementation details subsections:
<!-- toc -->
- [Background](#background)
- [Motivation](#motivation)
- [Goals](#goals)
- [Non-Goals](#non-goals)
- [Implementation Details](#implementation-details)
- [Test Plan](#test-plan)
- [Alternatives](#alternatives)
- [Open Questions](#open-questions)
<!-- /toc -->
I'm down to remove it all together.
There was a problem hiding this comment.
Yeah I think I'm leaning towards removing it all together too.
| and make progress. | ||
| --> | ||
|
|
||
| ## Implementation Details |
There was a problem hiding this comment.
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?
| Specify any additional frameworks or tools required for testing. | ||
| --> | ||
|
|
||
| ## Alternatives |
There was a problem hiding this comment.
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.
Yep! I think you could link other EPs here or have a length discussion section. Really depends on the feature!
| proposal will be implemented, this is the place to discuss them. | ||
| --> | ||
|
|
||
| ### Configuration |
There was a problem hiding this comment.
At a glance, these high-level sub-sections seem reasonable to me. I wonder whether we could get away with a high-level "Implementation Details" section without requiring predefined sub-sections to provide some more flexibility in structuring and make the EP process a bit less prescriptive. Just thinking aloud -- no strong opinion.
There was a problem hiding this comment.
Yeah good call- maybe I'll just list the subsection in the comment as a reminder of what sections can be included? This probably means we can also remove the index?
There was a problem hiding this comment.
I think a comment is a good middle ground as you're still guiding the author towards adding color around the major sub-systems in the project.
| 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 |
There was a problem hiding this comment.
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.
Hm, good call- maybe I should remove the "provisional" section? The EP has two stages:
- provisional (has not been fully implemented yet)
- implemented (code has merged, EP is up to date to reflect the state)
Maybe this should be a label/field on the issue itself?
|
|
||
| <!-- | ||
| 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.
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.
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:
- 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.
- 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.
| any review. | ||
| --> | ||
|
|
||
| * Issue: [#ID](URL to GitHub issue) |
There was a problem hiding this comment.
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.
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.
Description
Adds a template for enhancement proposals
API changes
None
Code changes
None
CI changes
None
Docs changes