54 lines
2.4 KiB
Markdown
54 lines
2.4 KiB
Markdown
# Design proposal template `<replace with your proposal's title>`
|
|
|
|
_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.
|
|
|
|
_Note_: The name of the file should follow the name pattern `<short meaningful words joined by '-'>_design.md`, e.g:
|
|
`listener-design.md`.
|
|
|
|
## Abstract
|
|
One to two sentences that describes the goal of this proposal and the problem being solved by the proposed change.
|
|
The reader should be able to tell by the title, and the opening paragraph, if this document is relevant to them.
|
|
|
|
## Background
|
|
One to two paragraphs of exposition to set the context for this proposal.
|
|
|
|
## 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.
|
|
|
|
|
|
## 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.
|
|
|
|
## Compatibility
|
|
A discussion of any compatibility issues that need to be considered
|
|
|
|
## Implementation
|
|
A description of the implementation, timelines, and any resources that have agreed to contribute.
|
|
|
|
## Open Issues
|
|
A discussion of issues relating to this proposal for which the author does not know the solution. This section may be omitted if there are none.
|