You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
50
-
label: "Context and scope"
56
+
label: 'Context and scope'
51
57
id: scope
52
58
type: textarea
53
59
validations:
@@ -56,7 +62,7 @@ body:
56
62
- attributes:
57
63
description: |
58
64
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.
59
-
label: "Goals and non-goals"
65
+
label: 'Goals and non-goals'
60
66
id: goals
61
67
type: textarea
62
68
validations:
@@ -68,7 +74,7 @@ body:
68
74
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.
69
75
70
76
The point of writing a document over a more formal medium is to provide the flexibility to express the problem at hand in an appropriate manner. Because of this, there is no explicit guidance on how to actually describe the design.
71
-
label: "The design"
77
+
label: 'The design'
72
78
id: design
73
79
type: textarea
74
80
validations:
@@ -77,21 +83,21 @@ body:
77
83
- attributes:
78
84
description: |
79
85
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.
80
-
label: "APIs"
86
+
label: 'APIs'
81
87
id: apis
82
88
type: textarea
83
89
84
90
- attributes:
85
91
description: |
86
92
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.
87
-
label: "Data storage"
93
+
label: 'Data storage'
88
94
id: persistence
89
95
type: textarea
90
96
91
97
- attributes:
92
98
description: |
93
99
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 feasibility of the design.
94
-
label: "Code and pseudo-code"
100
+
label: 'Code and pseudo-code'
95
101
id: pseudocode
96
102
type: textarea
97
103
@@ -104,7 +110,7 @@ body:
104
110
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.
105
111
106
112
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 great, and hence such a document should focus on selecting the best way given all identified trade-offs.
# Please edit the original at https://github.com/ory/meta/blob/master/templates/repository/common/.github/ISSUE_TEMPLATE/FEATURE-REQUEST.yml
3
3
4
-
description: "Suggest an idea for this project without a plan for implementation"
4
+
description:
5
+
'Suggest an idea for this project without a plan for implementation'
5
6
labels:
6
7
- feat
7
-
name: "Feature Request"
8
+
name: 'Feature Request'
8
9
body:
9
10
- attributes:
10
11
value: |
@@ -13,33 +14,39 @@ body:
13
14
If you already have a plan to implement a feature or a change, please create a [design document](https://github.com/aeneasr/gh-template-test/issues/new?assignees=&labels=rfc&template=DESIGN-DOC.yml) instead if the change is non-trivial!
14
15
type: markdown
15
16
- attributes:
16
-
label: "Preflight checklist"
17
+
label: 'Preflight checklist'
17
18
options:
18
-
- label: "I could not find a solution in the existing issues, docs, nor
19
-
discussions."
19
+
- label:
20
+
'I could not find a solution in the existing issues, docs, nor
21
+
discussions.'
20
22
required: true
21
-
- label: "I agree to follow this project's [Code of
0 commit comments