78ae68560b
When we introduced the design-driven contribution process we started
with a simple process and template for writing design docs, with the
intention to refine the process and template later. Now we gathered some
first experience with design discussions and we noticed/foresee a few
things that are not optimal yet, hence we want to improve the process
and the template.
Things that we want to improve:
1. Agreeing on a solution is difficult and design reviews can take a
long time. At the moment a design doc can only be submitted once
everyone agrees on the proposed solution.
2. If alternative solutions are proposed in comments they may not get
the amount of attention that they deserve.
3. It is seen as the responsibility of the design doc author to pick up
newly suggested alternative solutions and include them into the
design doc, but it's hard for the author to parse proposed solutions
from review comments and describe them accurately and with details in
the design doc.
4. If newly suggested alternative solutions get included into the design
doc they likely end up in the 'Alternatives Considered' section,
which makes them look less favored than the solution that was
initally advertised in the design doc.
5. Picking up a newly suggested solution as the new main solution
requires rewriting large parts of the design doc (hence there may be
some resistence against doing this).
6. There may be a tendency to favor the initially proposed solution
since more work was going into it and alternative solutions are only
briefly described.
7. Unrelated issues that are identified in design discussions tend to be
ignored and forgotten.
Our goal with design discussions was to collaborate as much as possible
and to write design docs together, in an iterative manner. With the
current process and template this is not working well. To improve this
we suggest to split design docs into multiple files that can be written
and refined by several persons in parallel:
* index.md:
Entry file that links to the files below.
* use-cases.md:
Describes the use-cases, acceptance criteria and background.
* solution-<n>.md:
Each possible solution (with the pros and cons, and implementation
details) is described in a separate file.
* conclusion.md:
Describes the conclusion of the design discussion.
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.
* All possible solutions are fairly discussed with their pros and cons,
and treated equally until a decision is made.
* Unrelated issues that are identified during discussions are extracted
into new design docs (initially consisting only of an index.md and a
use-cases.md file).
* 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.).
In addition some aspects of the documentation which were outdated have
been adapted to reality:
* Design docs are written in Markdown, not Asciidoc (hence the templates
were migrated).
* Design docs are reviewed and stored in the homepage repo, not in the
gerrit repo.
Furthermore some minor improvements were done:
* It is now recommended to use the 'dir' query operator to watch
design doc changes ('dir:pages/design-docs'), since it's more reliable
than the 'hashtag' operator which was suggested before since people
tend to forget to set this hashtag.
* Call out in the template for use-cases that Google-specific uses cases
should be clearly marked as such (the Google setup is pretty different
and not making this transparent can confuse readers).
* The design docs now talk about use-cases and acceptance criteria
instead of objectives, since formulating use-cases forces the author
to think from the users perspective and it's easier for reader to
understand how users are affected.
* The period in which the ESC is expected to comment on newly proposed
features was increased to 14 calendar days. This allows the ESC to
discuss the proposal in the ESC meeting, which happens bi-weekly,
before commenting on it.
Signed-off-by: Edwin Kempin <ekempin@google.com>
Change-Id: I401d5ec21ff2b568dab7346db212c9166537dfa9
128 lines
5.0 KiB
Plaintext
128 lines
5.0 KiB
Plaintext
= 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 are extracted into new design docs (initially
|
|
consisting only of an `index.md` and a `use-cases.md` file).
|
|
* 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] 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).
|
|
|
|
[[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.
|
|
|
|
Ideas for alternative solutions should be uploaded as a change that
|
|
describes the solution (see link:#collaboration[above]).
|
|
|
|
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 14 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]
|
|
. 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
|
|
---------
|