docs/designs/design-template.md

1 ---
3 # Document Guidelines - _Delete this section_
7 - Not all new features need a design document. If a feature can be contributed
11 - The focus of the document is to define the problem we need to solve and
12   analyse the trade-offs of different solutions. You should concentrate on
13   interactions between components, though analysing the trade-offs often
16 - Write this document as an [argumentative essay][argumentative-essay]. Good
19 [argumentative-essay]: https://www.grammarly.com/blog/argumentative-essay/
21 - This is not intended to be extensive documentation for a new feature.
23 - You should get your design reviewed and merged before writing your code.
30 - Your spec should be in Markdown format, like this template.
32 - Please wrap text at 79 columns.
34 - Please do not delete any of the sections in this template. If you have nothing
35   to say for a whole section, just write: None
37 - To view your .md file, see: https://stackedit.io/
39 - If you would like to provide a diagram with your spec, ASCII diagrams are
40   required. http://asciiflow.com/ is a very nice tool to assist with making
45 - Once ready for review, submit to gerrit and set the topic of the review to
48 ---
50 # Example design - this is the design title
62 What are the goals and NON-goals? Please make the objective understandable for
69 (1-2 paragraphs) What background context is necessary? You should mention
74 glossary if necessary. Note: this is background; do not write about your design,
79 (2-5 paragraphs) What are the constraints for the problem you are trying to
89 (2-5 paragraphs) A short and sweet overview of your implementation ideas. If you
94 write? What technologies will you use to write them?
110 - Does this proposal require a new repository? (Yes, No)
111 - Who will be the initial maintainer(s) of this repository?
112 - Which repositories are expected to be modified to execute this design?
113 - Make a list, and add listed repository maintainers to the gerrit review.