1f4febd00SPatrick Williams--- 2f4febd00SPatrick Williams 3f4febd00SPatrick Williams# Document Guidelines - _Delete this section_ 417dbdee6SKurt Taylor 533b25295SAndrew Jeffery## Document Content 69db762d8SAndrew Jeffery 7f4febd00SPatrick Williams- Not all new features need a design document. If a feature can be contributed 8f4febd00SPatrick Williams in a single reasonably small patchset that has little impact to any other 9f4febd00SPatrick Williams areas, it doesn't need a design discussion and documentation. 10f4febd00SPatrick Williams 11f4febd00SPatrick Williams- The focus of the document is to define the problem we need to solve and 129db762d8SAndrew Jeffery analyse the trade-offs of different solutions. You should concentrate on 139db762d8SAndrew Jeffery interactions between components, though analysing the trade-offs often 149db762d8SAndrew Jeffery requires you to explore how each might be implemented. 159db762d8SAndrew Jeffery 16f4febd00SPatrick Williams- Write this document as an [argumentative essay][argumentative-essay]. Good 179db762d8SAndrew Jeffery design proposals compel the reviewers agree with the proposal's conclusions. 189db762d8SAndrew Jeffery 199db762d8SAndrew Jeffery[argumentative-essay]: https://www.grammarly.com/blog/argumentative-essay/ 2033b25295SAndrew Jeffery 21f4febd00SPatrick Williams- This is not intended to be extensive documentation for a new feature. 2233b25295SAndrew Jeffery 23f4febd00SPatrick Williams- You should get your design reviewed and merged before writing your code. 24f4febd00SPatrick Williams However you are free to prototype the implementation, but remember that you 25f4febd00SPatrick Williams may learn of new requirements during the design review process that could 26f4febd00SPatrick Williams result in a very different solution. 2733b25295SAndrew Jeffery 2833b25295SAndrew Jeffery## Document Formatting 2933b25295SAndrew Jeffery 30f4febd00SPatrick Williams- Your spec should be in Markdown format, like this template. 3133b25295SAndrew Jeffery 32f4febd00SPatrick Williams- Please wrap text at 79 columns. 3333b25295SAndrew Jeffery 34f4febd00SPatrick Williams- Please do not delete any of the sections in this template. If you have nothing 35f4febd00SPatrick Williams to say for a whole section, just write: None 3633b25295SAndrew Jeffery 37f4febd00SPatrick Williams- To view your .md file, see: https://stackedit.io/ 38f4febd00SPatrick Williams 39f4febd00SPatrick Williams- If you would like to provide a diagram with your spec, ASCII diagrams are 4017dbdee6SKurt Taylor required. http://asciiflow.com/ is a very nice tool to assist with making 41f4febd00SPatrick Williams ASCII diagrams. Plain text will allow the review to proceed without having to 42f4febd00SPatrick Williams look at additional files which can not be viewed in Gerrit. It will also allow 43f4febd00SPatrick Williams inline feedback on the diagram itself. 4433b25295SAndrew Jeffery 45f4febd00SPatrick Williams- Once ready for review, submit to gerrit and set the topic of the review to 46f4febd00SPatrick Williams "design" 47f4febd00SPatrick Williams 48f4febd00SPatrick Williams--- 4917dbdee6SKurt Taylor 50ad3becf9SPatrick Venture# Example design - this is the design title 5117dbdee6SKurt Taylor 52f4febd00SPatrick WilliamsAuthor: < Name and Discord nickname > 53c343fe83SGunnar Mills 54f4febd00SPatrick WilliamsOther contributors: < Name and/or Discord nickname or `None` > 55c343fe83SGunnar Mills 56f4febd00SPatrick WilliamsCreated: < Date initially created in Month D, Yr format (e.g. June 17, 2020 or 57f4febd00SPatrick WilliamsDec 19, 2019)> 5817dbdee6SKurt Taylor 59ad3becf9SPatrick Venture## Problem Description 60f4febd00SPatrick Williams 61f4febd00SPatrick Williams(1 paragraph) What are we doing and why? What problem are you trying to solve? 62f4febd00SPatrick WilliamsWhat are the goals and NON-goals? Please make the objective understandable for 63f4febd00SPatrick Williamssomeone unfamiliar with this project by including the necessary context, but 64f4febd00SPatrick Williamskeep it short. Elaborate on the details below in the Background and Requirements 65f4febd00SPatrick Williamssections. 6617dbdee6SKurt Taylor 67ad3becf9SPatrick Venture## Background and References 68f4febd00SPatrick Williams 6917dbdee6SKurt Taylor(1-2 paragraphs) What background context is necessary? You should mention 70f4febd00SPatrick Williamsrelated work inside and outside of OpenBMC. What other Open Source projects are 71f4febd00SPatrick Williamstrying to solve similar problems? Try to use links or references to external 72f4febd00SPatrick Williamssources (other docs or Wikipedia), rather than writing your own explanations. 73f4febd00SPatrick WilliamsPlease include document titles so they can be found when links go bad. Include a 74f4febd00SPatrick Williamsglossary if necessary. Note: this is background; do not write about your design, 75f4febd00SPatrick Williamsspecific requirements details, or ideas to solve problems here. 7617dbdee6SKurt Taylor 77ad3becf9SPatrick Venture## Requirements 78f4febd00SPatrick Williams 7917dbdee6SKurt Taylor(2-5 paragraphs) What are the constraints for the problem you are trying to 80f4febd00SPatrick Williamssolve? Who are the users of this solution? What is required to be produced? What 81f4febd00SPatrick Williamsis the scope of this effort? Your job here is to quickly educate others about 82f4febd00SPatrick Williamsthe details you know about the problem space, so they can help review your 83f4febd00SPatrick Williamsimplementation. Roughly estimate relevant details. How big is the data? What are 84f44abd66SEd Tanousthe transaction rates? Bandwidth? How will the feature be configured, and what 85f44abd66SEd Tanousoption class does it fall into? (see architecture/optionality.md) 8617dbdee6SKurt Taylor 87ad3becf9SPatrick Venture## Proposed Design 88f4febd00SPatrick Williams 89f4febd00SPatrick Williams(2-5 paragraphs) A short and sweet overview of your implementation ideas. If you 90f4febd00SPatrick Williamshave alternative solutions to a problem, list them concisely in a bullet list. 91f4febd00SPatrick WilliamsThis should not contain every detail of your implementation, and do not include 92f4febd00SPatrick Williamscode. Use a diagram when necessary. Cover major structural elements in a very 93f4febd00SPatrick Williamssuccinct manner. Which technologies will you use? What new components will you 94f4febd00SPatrick Williamswrite? What technologies will you use to write them? 9517dbdee6SKurt Taylor 96ad3becf9SPatrick Venture## Alternatives Considered 97f4febd00SPatrick Williams 9817dbdee6SKurt Taylor(2 paragraphs) Include alternate design ideas here which you are leaning away 9917dbdee6SKurt Taylorfrom. Elaborate on why a design was considered and why the idea was rejected. 100f4febd00SPatrick WilliamsShow that you did an extensive survey about the state of the art. Compares your 101f4febd00SPatrick Williamsproposal's features & limitations to existing or similar solutions. 10217dbdee6SKurt Taylor 103ad3becf9SPatrick Venture## Impacts 104f4febd00SPatrick Williams 105f4febd00SPatrick WilliamsAPI impact? Security impact? Documentation impact? Performance impact? Developer 106f4febd00SPatrick Williamsimpact? Upgradability impact? 10717dbdee6SKurt Taylor 108ee848402SEd Tanous### Organizational 109f4febd00SPatrick Williams 110*dfd4abdbSPeter Delevoryas- Does this proposal require a new repository? (Yes, No) 111e2430b15SEd Tanous- Who will be the initial maintainer(s) of this repository? 112e2430b15SEd Tanous- Which repositories are expected to be modified to execute this design? 113e2430b15SEd Tanous- Make a list, and add listed repository maintainers to the gerrit review. 114ee848402SEd Tanous 115ad3becf9SPatrick Venture## Testing 116f4febd00SPatrick Williams 11717dbdee6SKurt TaylorHow will this be tested? How will this feature impact CI testing? 118