|
| 1 | +description: |
| 2 | + 'A design document is needed for non-trivial changes to the code base.' |
| 3 | +labels: |
| 4 | + - rfc |
| 5 | +name: 'Design Document' |
| 6 | +body: |
| 7 | + - attributes: |
| 8 | + value: | |
| 9 | + Thank you for writing this design document. |
| 10 | +
|
| 11 | + One of the key elements of Ory's software engineering culture is the use of defining software designs through design docs. These are relatively informal documents that the primary author or authors of a software system or application create before they embark on the coding project. The design doc documents the high level implementation strategy and key design decisions with emphasis on the trade-offs that were considered during those decisions. |
| 12 | +
|
| 13 | + Ory is leaning heavily on [Google's design docs process](https://www.industrialempathy.com/posts/design-docs-at-google/) |
| 14 | + and [Golang Proposals](https://github.com/golang/proposal). |
| 15 | +
|
| 16 | + Writing a design doc prior to contributing your change ensures that your ideas are checked with |
| 17 | + the community and maintainers. It will save you a lot of time developing things which might need changed |
| 18 | + after code reviews, and your pull requests will be merged faster. |
| 19 | + type: markdown |
| 20 | + - attributes: |
| 21 | + label: 'Preflight checklist' |
| 22 | + options: |
| 23 | + - label: |
| 24 | + 'I could not find a solution in the existing issues, docs, nor |
| 25 | + discussions.' |
| 26 | + required: true |
| 27 | + - label: |
| 28 | + "I agree to follow this project's [Code of |
| 29 | + Conduct](https://github.com/ory/examples/blob/master/CODE_OF_CONDUCT.md)." |
| 30 | + required: true |
| 31 | + - label: |
| 32 | + "I have read and am following this repository's [Contribution |
| 33 | + Guidelines](https://github.com/ory/examples/blob/master/CONTRIBUTING.md)." |
| 34 | + required: true |
| 35 | + - label: |
| 36 | + 'This issue affects my [Ory Cloud](https://www.ory.sh/) project.' |
| 37 | + - label: |
| 38 | + 'I have joined the [Ory Community Slack](https://slack.ory.sh).' |
| 39 | + - label: |
| 40 | + 'I am signed up to the [Ory Security Patch |
| 41 | + Newsletter](https://ory.us10.list-manage.com/subscribe?u=ffb1a878e4ec6c0ed312a3480&id=f605a41b53).' |
| 42 | + id: checklist |
| 43 | + type: checkboxes |
| 44 | + - attributes: |
| 45 | + description: | |
| 46 | + This section gives the reader a very rough overview of the landscape in which the new system is being built and what is actually being built. This isn’t a requirements doc. Keep it succinct! The goal is that readers are brought up to speed but some previous knowledge can be assumed and detailed info can be linked to. This section should be entirely focused on objective background facts. |
| 47 | + label: 'Context and scope' |
| 48 | + id: scope |
| 49 | + type: textarea |
| 50 | + validations: |
| 51 | + required: true |
| 52 | + |
| 53 | + - attributes: |
| 54 | + description: | |
| 55 | + A short list of bullet points of what the goals of the system are, and, sometimes more importantly, what non-goals are. Note, that non-goals aren’t negated goals like “The system shouldn’t crash”, but rather things that could reasonably be goals, but are explicitly chosen not to be goals. A good example would be “ACID compliance”; when designing a database, you’d certainly want to know whether that is a goal or non-goal. And if it is a non-goal you might still select a solution that provides it, if it doesn’t introduce trade-offs that prevent achieving the goals. |
| 56 | + label: 'Goals and non-goals' |
| 57 | + id: goals |
| 58 | + type: textarea |
| 59 | + validations: |
| 60 | + required: true |
| 61 | + |
| 62 | + - attributes: |
| 63 | + description: | |
| 64 | + This section should start with an overview and then go into details. |
| 65 | + The design doc is the place to write down the trade-offs you made in designing your software. Focus on those trade-offs to produce a useful document with long-term value. That is, given the context (facts), goals and non-goals (requirements), the design doc is the place to suggest solutions and show why a particular solution best satisfies those goals. |
| 66 | +
|
| 67 | + The point of writing a document over a more formal medium is to provide the flexibility to express the problem set at hand in an appropriate manner. Because of this, there is no explicit guidance for how to actually describe the design. |
| 68 | + label: 'The design' |
| 69 | + id: design |
| 70 | + type: textarea |
| 71 | + validations: |
| 72 | + required: true |
| 73 | + |
| 74 | + - attributes: |
| 75 | + description: | |
| 76 | + If the system under design exposes an API, then sketching out that API is usually a good idea. In most cases, however, one should withstand the temptation to copy-paste formal interface or data definitions into the doc as these are often verbose, contain unnecessary detail and quickly get out of date. Instead focus on the parts that are relevant to the design and its trade-offs. |
| 77 | + label: 'APIs' |
| 78 | + id: apis |
| 79 | + type: textarea |
| 80 | + |
| 81 | + - attributes: |
| 82 | + description: | |
| 83 | + Systems that store data should likely discuss how and in what rough form this happens. Similar to the advice on APIs, and for the same reasons, copy-pasting complete schema definitions should be avoided. Instead focus on the parts that are relevant to the design and its trade-offs. |
| 84 | + label: 'Data storage' |
| 85 | + id: persistence |
| 86 | + type: textarea |
| 87 | + |
| 88 | + - attributes: |
| 89 | + description: | |
| 90 | + Design docs should rarely contain code, or pseudo-code except in situations where novel algorithms are described. As appropriate, link to prototypes that show the implementability of the design. |
| 91 | + label: 'Code and pseudo-code' |
| 92 | + id: pseudocode |
| 93 | + type: textarea |
| 94 | + |
| 95 | + - attributes: |
| 96 | + description: | |
| 97 | + One of the primary factors that would influence the shape of a software design and hence the design doc, is the degree of constraint of the solution space. |
| 98 | +
|
| 99 | + On one end of the extreme is the “greenfield software project”, where all we know are the goals, and the solution can be whatever makes the most sense. Such a document may be wide-ranging, but it also needs to quickly define a set of rules that allow zooming in on a manageable set of solutions. |
| 100 | +
|
| 101 | + On the other end are systems where the possible solutions are very well defined, but it isn’t at all obvious how they could even be combined to achieve the goals. This may be a legacy system that is difficult to change and wasn’t designed to do what you want it to do or a library design that needs to operate within the constraints of the host programming language. |
| 102 | +
|
| 103 | + In this situation you may be able to enumerate all the things you can do relatively easily, but you need to creatively put those things together to achieve the goals. There may be multiple solutions, and none of them are really great, and hence such a document should focus on selecting the best way given all identified trade-offs. |
| 104 | + label: 'Degree of constraint' |
| 105 | + id: constrait |
| 106 | + type: textarea |
| 107 | + |
| 108 | + - attributes: |
| 109 | + description: | |
| 110 | + This section lists alternative designs that would have reasonably achieved similar outcomes. The focus should be on the trade-offs that each respective design makes and how those trade-offs led to the decision to select the design that is the primary topic of the document. |
| 111 | +
|
| 112 | + While it is fine to be succinct about solution that ended up not being selected, this section is one of the most important ones as it shows very explicitly why the selected solution is the best given the project goals and how other solutions, that the reader may be wondering about, introduce trade-offs that are less desirable given the goals. |
| 113 | +
|
| 114 | + label: Alternatives considered |
| 115 | + id: alternatives |
| 116 | + type: textarea |
0 commit comments