diff --git a/docs/design/template.md b/docs/design/template.md new file mode 100644 index 0000000..f764451 --- /dev/null +++ b/docs/design/template.md @@ -0,0 +1,53 @@ +# Design proposal template `` + +_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 `_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.