| :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 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,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 |
| --------- |