1.8 KiB
Design proposal template (replace with your proposal's title)
One to two sentences that describes the goal of this proposal. The reader should be able to tell by the title, and the opening paragraph, if this document is relevant to them.
Note: The preferred style for design documents is one sentence per line. Do not wrap lines. This aids in review of the document as changes to a line are not obscured by the reflowing those changes caused and has a side effect of avoiding debate about one or two space after a period.
Goals
- A short list of things which will be accomplished by implementing this proposal.
- Two things is ok.
- Three is pushing it.
- More than three goals suggests that the proposal's scope is too large.
Non Goals
- A short list of items which are:
- a. out of scope
- b. follow on items which are deliberately excluded from this proposal.
Background
One to two paragraphs of exposition to set the context for this proposal.
High-Level Design
One to two paragraphs that describe the high level changes that will be made to implement this proposal.
Detailed Design
A detailed design describing how the changes to the product should be made.
The names of types, fields, interfaces, and methods should be agreed on here, not debated in code review. The same applies to changes in CRDs, YAML examples, and so on.
Ideally the changes should be made in sequence so that the work required to implement this design can be done incrementally, possibly in parallel.
Alternatives Considered
If there are alternative high level or detailed designs that were not pursued they should be called out here with a brief explanation of why they were not pursued.
Security Considerations
If this proposal has an impact to the security of the product, its users, or data stored or transmitted via the product, they must be addressed here.