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