c507dbb8de
The ESC is meeting only once per month now (instead of bi-weekly). Adapt the reaction time for the ESC on designs accordingly. The meeting frequency of the ESC was reduced to reduce the workload of the ESC members. During the last election for ESC members it turned out that some people had concerns to candidate due to the high work volume that is expected from ESC members. We need to reduce the workload for ESC members so that we will find volunteers for this role also in the future. Change-Id: I6a07c8778f92a83422703cb90ff6c6722f88da88 Signed-off-by: Edwin Kempin <ekempin@google.com>
153 lines
6.4 KiB
Plaintext
153 lines
6.4 KiB
Plaintext
: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.
|
|
|
|
[[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
|
|
---------
|