neat-enhancement-idea
To get started with this template:
- Make a copy of this template. Copy this template into a new file.
- Fill out the “overview” sections. This includes the Summary and Motivation sections. These should be easy and explain why the community should desire this enhancement.
- Create a PR. Assign it to folks with expertise in that domain to help sponsor the process.
Start by filling out the header with the metadata for this enhancement.
Neat Enhancement Idea
This is the title of the enhancement. Keep it simple and descriptive. A good title can help communicate what the enhancement is and should be considered as part of any review.
The YAML title should be lowercased and spaces/punctuation should be
replaced with -.
The Metadata section above is intended to support the creation of tooling
around the enhancement process.
Summary
The Summary section is incredibly important for producing high quality
user-focused documentation such as release notes or a development roadmap. It
should be possible to collect this information before implementation begins in
order to avoid requiring implementors to split their attention between writing
release notes and implementing the feature itself.
A good summary is no more than one paragraph in length. More detail should go into the following sections.
Motivation
This section is for explicitly listing the motivation, goals and non-goals of this proposal. Describe why the change is important and the benefits to users.
Goals
Summarize the specific goals of the proposal. How will we know that this has succeeded? A good goal describes something a user wants from their perspective, and does not include the implementation details from the proposal.
Non-Goals
What is out of scope for this proposal? Listing non-goals helps to focus discussion and make progress. Highlight anything that is being deferred to a later phase of implementation that may call for its own enhancement.
Proposal
This is where we get down to the nitty gritty of what the proposal actually is. Describe clearly what will be changed, including all of the components that need to be modified and how they will be different. Include the reason for each choice in the design and implementation that is proposed here, and expand on reasons for not choosing alternatives in the Alternatives section at the end of the document.
API Extensions
API Extensions are CRDs, admission and conversion webhooks, aggregated API servers, and finalizers, i.e. those mechanisms that change the Kubernetes API surface and behaviour.
-
Name the API extensions this enhancement adds or modifies.
-
Does this enhancement modify the behaviour of existing resources, especially those owned by other parties than the authoring team (including upstream resources), and, if yes, how? Please add those other parties as reviewers to the enhancement.
Examples:
- Adds a finalizer to namespaces. Namespace cannot be deleted without our controller running.
- Restricts the label format for objects to X.
- Defaults field Y on object kind Z.
Fill in the operational impact of these API Extensions in the “Operational Aspects of API Extensions” section.
Implementation Details/Notes/Constraints [optional]
What are the caveats to the implementation? What are some important details that didn’t come across above. Go in to as much detail as necessary here. This might be a good place to talk about core concepts and how they relate.
Risks and Mitigations
What are the risks of this proposal and how do we mitigate. Think broadly. For example, consider both security and how this will impact the larger operator ecosystem.
How will security be reviewed and by whom?
How will UX be reviewed and by whom?
Consider including folks that also work outside your immediate sub-project.
Design Details
Open Questions [optional]
This is where to call out areas of the design that require closure before deciding to implement the design. For instance,
- This requires exposing previously private resources which contain sensitive information. Can we do this?
Implementation History
Major milestones in the life cycle of a proposal should be tracked in Implementation History.
Drawbacks
The idea is to find the best form of an argument why this enhancement should not be implemented.
Alternatives
Similar to the Drawbacks section the Alternatives section is used to
highlight and record other possible approaches to delivering the value proposed
by an enhancement.