1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
:linkattrs:
= Gerrit Code Review - Design Docs
For the link:dev-contributing.html#design-driven-contribution-process[
design-driven contribution process] it is required to specify features
upfront in a design doc.
[[structure]]
== Design Doc Structure
A design doc should discuss the following aspects:
* Use-Cases:
The interactions between a user and a system to attain particular
goals.
* Acceptance Criteria
Conditions that must be satisfied to consider the feature as done.
* Background:
Stuff one needs to know to understand the use-cases (e.g. motivating
examples, previous versions and problems, links to related
changes/design docs, etc.)
* Possible Solutions:
Possible solutions with the pros and cons, and explanation of
implementation details.
* Conclusion:
Which decision was made and what were the reasons for it.
[[collaboration]]
As community we want to collaborate on design docs as much as possible
and write them together, in an iterative manner. To make this work well
design docs are split into multiple files that can be written and
refined by several persons in parallel:
* `index.md`:
Entry file that links to the files below (also see
'dev-design-doc-index-template.md').
* `use-cases.md`:
Describes the use-cases, acceptance criteria and background (also see
'dev-design-doc-use-cases-template.md').
* `solution-<n>.md`:
Each possible solution (with the pros and cons, and implementation
details) is described in a separate file (also see
'dev-design-doc-solution-template.md').
* `conclusion.md`:
Describes the conclusion of the design discussion (also see
'dev-design-doc-conclusion-template.md').
[[expectation]]
It is expected that:
* An agreement on the use-cases is achieved before solutions are being
discussed in detail.
* Anyone who has ideas for an alternative solution uploads a change
with a `solution-<n>.md` that describes their solution. In case of
doubt whether an idea is a refinement of an existing solution or an
alternative solution, it's up to the owner of the discussed solution
to decide if the solution should be updated, or if the proposer
should start a new alternative solution.
* All possible solutions are fairly discussed with their pros and cons,
and treated equally until a conclusion is made.
* Unrelated issues (judged by the design doc owner) that are identified
during discussions may be extracted into new design docs (initially
consisting only of an `index.md` and a `use-cases.md` file). Doing so
is optional yet can be done by either the design owner or reviewers.
* Changes making iterative improvements can be submitted frequently
(e.g. additional uses-cases can be added later, solutions can be
submitted without describing implementation details, etc.).
* After a conclusion has been approved contributors are expected to
keep the design doc updated and fill in gaps while they go forward
with the implementation.
[[propose]]
== How to propose a new design?
To propose a new design, upload a change to the
link:https://gerrit-review.googlesource.com/admin/repos/homepage[
homepage,role=external,window=_blank] repository that adds a new folder under `pages/design-docs/`
which contains at least an `index.md` and a `uses-cases.md` file (see
link:#structure[design doc structure] above).
Pushing a design doc for review requires to be a
link:dev-roles.html#contributor[contributor].
When contributing design docs, contributors should make clear whether
they are committed to do the implementation. It is possible to
contribute designs without having resources to do the implementation,
but in this case the implementation is only done if someone volunteers
to do it (which is not guaranteed to happen).
Only very few maintainers actively watch out for uploaded design docs.
To raise awareness you may want to send a notification to the
link:https://groups.google.com/d/forum/repo-discuss[repo-discuss,role=external,window=_blank]
mailing list about your uploaded design doc. But the discussion should
not take place on the mailing list, comments should be made by reviewing
the change in Gerrit.
[[review]]
== Design doc review
Everyone in the link:dev-roles.html[Gerrit community] is welcome to
take part in the design review and comment on the design. As such, every
design reviewer is expected to respect the community
link:https://www.gerritcodereview.com/codeofconduct.html[Code of Conduct,role=external,window=_blank].
Positive `Code-Review` votes on changes that add/modify design docs are
sticky. This means any `Code-Review+1` and `Code-Review+2` vote is
preserved when a new patch set is uploaded. If a new patch set makes
significant changes, the uploader of the new patch set must start a new
review round by removing all positive `Code-Review` votes from the
change manually.
Ideas for alternative solutions should be uploaded as a change that
describes the solution (see link:#collaboration[above]). This should be
done as early as possible during the review process, so that related
comment threads stop there and do not clutter the current review. It is up
to the alternative reviews to then host their related comments.
Verification should be based on the generated `jekyll` site using the
local `docker`, rather than via the rendering in `gitiles` (via
`gerrit-review`).
Changes which make a conclusion on a design (changes that add/change
the `conclusion.md` file, see link:#structure[Design Doc Structure])
should stay open for a minimum of 10 calendar days so that everyone has
a fair chance to see them. It is important that concerns regarding a
feature are raised during this time frame since once a conclusion is
approved and submitted the implementation may start immediately.
Other design doc changes can and should be submitted quickly so that
collaboration and iterative refinements work smoothly (see
link:#collaboration[above]).
For proposed features the contributor should hear back from the
link:dev-processes.html#steering-committee[engineering steering
committee] within 30 calendar days whether the proposed feature is in
scope of the project and if it can be accepted.
[[meetings]]
=== Meeting discussions
If the Gerrit review doesn't start efficiently enough, stalls, gets off-track
too much or becomes overly complex, one can use a meeting to refocus it. From
that review thread, the organizer can volunteer oneself, or be proposed (even
requested) by a reviewer. link:https://www.gerritcodereview.com/members.html#community-managers[
Community managers,role=external,window=_blank] may help facilitate that if
ultimately necessary.
[[watch-designs]]
== How to get notified for new design docs?
. Go to the
link:https://gerrit-review.googlesource.com/settings/#Notifications[
notification settings,role=external,window=_blank]
. Add a project watch for the `homepage` repository with the following
query: `dir:pages/design-docs`
GERRIT
------
Part of link:index.html[Gerrit Code Review]
SEARCHBOX
---------
|
