Skip to content

Latest commit

 

History

History
53 lines (37 loc) · 2.39 KB

_template.md

File metadata and controls

53 lines (37 loc) · 2.39 KB
Raw

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.