2.7 KiB
Title
This is the title of the spec. Keep it simple and descriptive. A good title can help communicate what the spec is and should be considered as part of any review.
The title should be lowercased and spaces/punctuation should be replaced with
-.
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 implementers to split their attention between writing
release notes and implementing the feature itself. Ensure that the tone and
content of the Summary section is useful for a wide audience.
A good summary is probably at least a paragraph in length.
Goals
List the specific goals of the spec. How will we know that this has succeeded?
Non-Goals
What is out of scope for this spec? Listing non-goals helps to focus discussion and make progress.
Proposal
This is where we get down to the nitty gritty of what the proposal actually is.
User Stories [optional]
Detail the things that people will be able to do if this spec is implemented. Include as much detail as possible so that people can understand the "how" of the system. The goal here is to make this feel real for users without getting bogged down.
Story 1
Story 2
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 kubernetes ecosystem.
How will security be reviewed and by whom? How will UX be reviewed and by whom?
Consider including folks that also work outside the SIG or subproject.
Design Details
Upgrade / Downgrade / Migration Strategy
If applicable, how will the component be upgraded and downgraded? Does this spec propose migrating users from one component or behaviour to another?
Public API changes
Does the spec propose a public API-facing change? If so, describe the impact of changes.
Drawbacks [optional]
Why should this spec not be implemented.
Alternatives [optional]
Similar to the Drawbacks section the Alternatives section is used to
highlight and record other possible approaches to delivering the value proposed
by the spec.