1--- 2 3# Document Guidelines - _Delete this section_ 4 5## Document Content 6 7- Not all new features need a design document. If a feature can be contributed 8 in a single reasonably small patchset that has little impact to any other 9 areas, it doesn't need a design discussion and documentation. 10 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 14 requires you to explore how each might be implemented. 15 16- Write this document as an [argumentative essay][argumentative-essay]. Good 17 design proposals compel the reviewers agree with the proposal's conclusions. 18 19[argumentative-essay]: https://www.grammarly.com/blog/argumentative-essay/ 20 21- This is not intended to be extensive documentation for a new feature. 22 23- You should get your design reviewed and merged before writing your code. 24 However you are free to prototype the implementation, but remember that you 25 may learn of new requirements during the design review process that could 26 result in a very different solution. 27 28## Document Formatting 29 30- Your spec should be in Markdown format, like this template. 31 32- Please wrap text at 79 columns. 33 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 36 37- To view your .md file, see: https://stackedit.io/ 38 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 41 ASCII diagrams. Plain text will allow the review to proceed without having to 42 look at additional files which can not be viewed in Gerrit. It will also allow 43 inline feedback on the diagram itself. 44 45- Once ready for review, submit to gerrit and set the topic of the review to 46 "design" 47 48--- 49 50# Example design - this is the design title 51 52Author: < Name and Discord nickname > 53 54Other contributors: < Name and/or Discord nickname or `None` > 55 56Created: < Date initially created in Month D, Yr format (e.g. June 17, 2020 or 57Dec 19, 2019)> 58 59## Problem Description 60 61(1 paragraph) What are we doing and why? What problem are you trying to solve? 62What are the goals and NON-goals? Please make the objective understandable for 63someone unfamiliar with this project by including the necessary context, but 64keep it short. Elaborate on the details below in the Background and Requirements 65sections. 66 67## Background and References 68 69(1-2 paragraphs) What background context is necessary? You should mention 70related work inside and outside of OpenBMC. What other Open Source projects are 71trying to solve similar problems? Try to use links or references to external 72sources (other docs or Wikipedia), rather than writing your own explanations. 73Please include document titles so they can be found when links go bad. Include a 74glossary if necessary. Note: this is background; do not write about your design, 75specific requirements details, or ideas to solve problems here. 76 77## Requirements 78 79(2-5 paragraphs) What are the constraints for the problem you are trying to 80solve? Who are the users of this solution? What is required to be produced? What 81is the scope of this effort? Your job here is to quickly educate others about 82the details you know about the problem space, so they can help review your 83implementation. Roughly estimate relevant details. How big is the data? What are 84the transaction rates? Bandwidth? How will the feature be configured, and what 85option class does it fall into? (see architecture/optionality.md) 86 87## Proposed Design 88 89(2-5 paragraphs) A short and sweet overview of your implementation ideas. If you 90have alternative solutions to a problem, list them concisely in a bullet list. 91This should not contain every detail of your implementation, and do not include 92code. Use a diagram when necessary. Cover major structural elements in a very 93succinct manner. Which technologies will you use? What new components will you 94write? What technologies will you use to write them? 95 96## Alternatives Considered 97 98(2 paragraphs) Include alternate design ideas here which you are leaning away 99from. Elaborate on why a design was considered and why the idea was rejected. 100Show that you did an extensive survey about the state of the art. Compares your 101proposal's features & limitations to existing or similar solutions. 102 103## Impacts 104 105API impact? Security impact? Documentation impact? Performance impact? Developer 106impact? Upgradability impact? 107 108### Organizational 109 110- Does this repository 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. 114 115## Testing 116 117How will this be tested? How will this feature impact CI testing? 118