Document design-driven contribution process
Establishing a new design-driven contribution process is part of a
proposal from Google to foster a better collaboration within the Gerrit
community (see change I27e432cce).
The goal is to:
* ensure that new features are in line with the project scope
* ensure that new features are well aligned with other features
* have a defined workflow for dicussing new features and raising
concerns
* reduce the risk of unfinished features
* making reviews of large features easier by providing more context
upfront
These goals should be achieved by a new design-driven contribution
process that requires a design doc to be written first:
* contributor specifies a feature upfront in a design doc
* a public design review is done where concerns can be raised
* the steering committee gives early feedback whether the feature is in
line with the project scope and hence has chances to be accepted
* the steering committee is in charge of approving/rejecting the design
doc
* once approved the steering committee is committed to the feature and
accepts it when it is implemented
* the contributor drives the implementation (and anyone from the Gerrit
community can help)
Following the design-driven contribution process is required for
large/complex features. For small contributions (documentation updates,
bug fixes, small features) contributors can continue to push changes
for review without any prior alignment. This way of contributing is now
called light-weight contribution process.
If contributors chose the light-weight contribution process and during
the review it turns out that the feature is too large or complex,
maintainers can require to follow the design-driven contribution process
instead. Telling the contributor that their changes will not get
submitted without making a design first is better than just ignoring the
changes without feedback as it may happen nowadays.
The documented contribution processes apply to everyone that contributes
code to the Gerrit project, including maintainers and including Google.
We believe that this makes the work Google is doing more transparent to
the community, as there will be a public design doc and a guaranteed
review period where concerns can be raised.
Among maintainers there is an agreement that design docs should be
reviewed in Gerrit. This change only defines an initial design doc
review process. It allows us to start working with the new process
immediately and is intentionally kept as simple as possible. The
steering committee is responsible to refine it, e.g.:
* Where are design docs stored?
(gerrit repo vs. separate repo)
* Which syntax should be used for design docs?
(Asciidoc vs Markdown)
* Should we rely on ADRs?
(https://www.thoughtworks.com/radar/techniques/lightweight-architecture-decision-records)
* Which further sections should be added to the design doc template?
(e.g. UX impact, required refactorings)
* Which criteria should be used to decide if a feature is large/complex
so that the design-driven contribution process becomes required?
Answers to these questions should be documented by follow-up changes.
Changes with new design docs 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 design is approved and submitted the implementation
may start immediately.
In order to be accepted/submitted it is not necessary that the design
doc fully specifies all the details, but the idea of the feature and how
it fits into Gerrit should be sufficiently clear (judged by the steering
committee). Contributors are expected to keep the design doc updated and
fill in gaps while they go forward with the implementation. We expect
that implementing the feature and updating the design doc will be an
iterative process.
Signed-off-by: Edwin Kempin <ekempin@google.com>
Change-Id: If1b6f71e7fee9c775c8768334408664f338e9933
diff --git a/Documentation/dev-community.txt b/Documentation/dev-community.txt
index 9e24a71..fea68a7 100644
--- a/Documentation/dev-community.txt
+++ b/Documentation/dev-community.txt
@@ -16,7 +16,10 @@
* link:dev-design.html[System Design]
* Processes
** link:dev-processes.html#project-governance[Project Governance / Steering Committee]
-** link:dev-contributing.html[Contribution Process]
+** link:dev-contributing.html#contribution-processes[Contribution Processes]
+*** link:dev-contributing.html#lightweight-contribution-process[Lightweight Contribution Process]
+*** link:dev-contributing.html#design-driven-contribution-process[Design-Driven Contribution Process]
+** link:dev-design-docs.html#review[Design doc reviews]
** link:dev-processes.html#dev-in-stable-branches[Development in stable branches]
** link:dev-processes.html#backporting[Backporting to stable branches]
** link:dev-processes.html#upgrading-libraries[Upgrading Libraries]
@@ -31,8 +34,12 @@
[[how-to-contribute]]
== How to contribute?
* link:dev-cla.html[Contributor License Agreement]
-* link:dev-contributing.html[Contributing to Gerrit]
+* link:dev-contributing.html#contribution-processes[Contribution Processes]
+** link:dev-contributing.html#lightweight-contribution-process[Lightweight Contribution Process]
+** link:dev-contributing.html#design-driven-contribution-process[Design-Driven Contribution Process]
+* link:dev-design-docs.html[Design Docs]
* link:dev-readme.html[Developer Setup]
+* link:https://gerrit.googlesource.com/gerrit/+/master/polygerrit-ui[Polymer Frontend Developer Setup]
* link:dev-crafting-changes.html[Crafting Changes]
* link:dev-starter-projects.html[Starter Projects]
diff --git a/Documentation/dev-contributing.txt b/Documentation/dev-contributing.txt
index 5d6941d..82396f1 100644
--- a/Documentation/dev-contributing.txt
+++ b/Documentation/dev-contributing.txt
@@ -6,13 +6,73 @@
In order to contribute to Gerrit a link:dev-cla.html[Contributor
License Agreement] must be completed before contributions are accepted.
-[[contribution-process]]
-== Contribution Process
+[[contribution-processes]]
+== Contribution Processes
+
+The Gerrit project offers two contribution processes:
+
+* link:#lightweight-contribution-process[Lightweight Contribution
+ Process]
+* link:#design-driven-contribution-process[Design-Driven Contribution
+ Process]
+
+The lightweight contribution process has little overhead and is best
+suited for small contributions (documentation updates, bug fixes, small
+features). Contributions are pushed as changes and
+link:dev-roles.html#maintainer[maintainers] review them adhoc.
+
+For large/complex features, it is required to follow the
+link:#design-driven-contribution-process[design-driven contribution
+process] and specify the feature in a link:dev-design-docs.html[design
+doc] before starting with the implementation.
+
+If link:dev-roles.html#contributor[contributors] choose the
+lightweight contribution process and during the review it turns out
+that the feature is too large or complex,
+link:dev-roles.html#maintainer[maintainers] can require to follow the
+design-driven contribution process instead.
+
+If you are in doubt which process is right for you, consult the
+link:https://groups.google.com/d/forum/repo-discuss[repo-discuss]
+mailing list.
+
+These contribution processes apply to everyone who contributes code to
+the Gerrit project, including link:dev-roles.html#maintainer[
+maintainers]. When reading this document, keep in mind that maintainers
+are also contributors when they contribute code.
+
+[[comparison]]
+=== Quick Comparison
+
+[options="header"]
+|======================
+| |Lightweight Contribution Process|Design-Driven Contribution Process
+|Overhead|low (write good commit message, address review comments)|
+high (write link:dev-design-docs.html[design doc] and get it approved)
+|Technical Guidance|by reviewer|during the design review and by
+reviewer
+|Caveats |features may get vetoed after the implementation was already
+done, maintainers may make the design-driven contribution process
+required if a change gets too complex/large|design doc must stay open
+for a minimum of 10 calendar days
+|Applicable to|documentation updates, bug fixes, small features|
+large/complex features
+|======================
+
+[[lightweight-contribution-process]]
+=== Lightweight Contribution Process
+
+The lightweight contribution process has little overhead and is best
+suited for small contributions (documentation updates, bug fixes, small
+features). For large/complex features the
+link:#design-driven-contribution-process[design-driven contribution
+process] is required.
As Gerrit is a code review tool, naturally contributions will
be reviewed before they will get submitted to the code base. To
start your contribution, please make a git commit and upload it
-for review to the main Gerrit review server. To help speed up the
+for review to the link:https://gerrit-review.googlesource.com/[
+gerrit-review.googlesource.com] Gerrit server. To help speed up the
review of your change, review these link:dev-crafting-changes.html[
guidelines] before submitting your change. You can view the pending
Gerrit contributions and their statuses
@@ -20,24 +80,103 @@
Depending on the size of that list it might take a while for
your change to get reviewed. Naturally there are fewer
-approvers than contributors; so anything that you can do to
-ensure that your contribution will undergo fewer revisions
-will speed up the contribution process. This includes helping
-out reviewing other people's changes to relieve the load from
-the approvers. Even if you are not familiar with Gerrit's
-internals, it would be of great help if you can download, try
-out, and comment on new features. If it works as advertised,
-say so, and if you have the privileges to do so, go ahead
-and give it a +1 Verified. If you would find the feature
-useful, say so and give it a +1 code review.
+link:dev-roles.html#maintainer[maintainers], that can approve changes,
+than link:dev-roles.html#contributor[contributors]; so anything that
+you can do to ensure that your contribution will undergo fewer
+revisions will speed up the contribution process. This includes
+helping out reviewing other people's changes to relieve the load from
+the maintainers. Even if you are not familiar with Gerrit's internals,
+it would be of great help if you can download, try out, and comment on
+new features. If it works as advertised, say so, and if you have the
+privileges to do so, go ahead and give it a `+1 Verified`. If you
+would find the feature useful, say so and give it a `+1 Code Review`.
-And finally, the quicker you respond to the comments of your
-reviewers, the quicker your change might get merged! Try to
-reply to every comment after submitting your new patch,
-particularly if you decided against making the suggested change.
-Reviewers don't want to seem like nags and pester you if you
-haven't replied or made a fix, so it helps them know if you
-missed it or decided against it.
+And finally, the quicker you respond to the comments of your reviewers,
+the quicker your change might get merged! Try to reply to every
+comment after submitting your new patch, particularly if you decided
+against making the suggested change. Reviewers don't want to seem like
+nags and pester you if you haven't replied or made a fix, so it helps
+them know if you missed it or decided against it.
+
+[[design-driven-contribution-process]]
+=== Design-driven Contribution Process
+
+The design-driven contribution process applies to large/complex
+features.
+
+For large/complex features it is important to:
+
+* agree on the functionality and scope before spending too much time
+ on the implementation
+* ensure that they are in line with Gerrit's project scope and vision
+* ensure that they are well aligned with other features
+* think about possibilities how the feature could be evolved over time
+
+This is why for large/complex features it is required to describe the
+feature in a link:dev-design-docs.html[design doc] and get it approved
+by the link:dev-processes.html#steering-committee[steering committee],
+before starting the implementation.
+
+The design-driven contribution process has the following steps:
+
+* A link:dev-roles.html#contributor[contributor]
+ link:dev-design-docs.html#propose[proposes] a new feature by
+ uploading a change with a link:dev-design-docs.html[design doc].
+* The design doc is link:dev-design-docs.html#review[reviewed] by
+ interested parties from the community. The design review is public
+ and everyone can comment and raise concerns.
+* Design docs should stay open for a minimum of 10 calendar days so
+ that everyone has a fair chance to join the review.
+* Within 14 calendar days the contributor should hear back from the
+ link:dev-processes.html#steering-committee[steering committee]
+ whether the proposed feature is in scope of the project and if it can
+ be accepted.
+* To be submitted, the design doc needs to be approved by the
+ link:dev-processes.html#steering-committee[steering committee].
+* After the design was approved, the implementation is done by pushing
+ changes for review, see link:#lightweight-contribution-process[
+ lightweight contribution process]. Changes that are associated with
+ a design should all share a common hashtag. The contributor is the
+ main driver of the implementation and responsible that it is done.
+ Others from the Gerrit community are usually much welcome to help
+ with the implementation.
+
+In order to be accepted/submitted, it is not necessary that the design
+doc fully specifies all the details, but the idea of the feature and
+how it fits into Gerrit should be sufficiently clear (judged by the
+steering committee). Contributors are expected to keep the design doc
+updated and fill in gaps while they go forward with the implementation.
+We expect that implementing the feature and updating the design doc
+will be an iterative process.
+
+While the design doc is still in review, contributors may already start
+with the implementation (e.g. do some prototyping to demonstrate parts
+of the proposed design), but those changes should not be submitted
+while the design wasn't approved yet.
+
+By approving a design, the steering committee commits to:
+
+* Accepting the feature when it is implemented.
+
+If the implementation of a feature gets stuck and it's unclear whether
+the feature gets fully done, it should be discussed with the steering
+committee how to proceed. If the contributor cannot commit to finish
+the implementation and no other contributor can take over, changes that
+have already been submitted for the feature might get reverted so that
+there is no unused or half-finished code in the code base.
+
+For contributors, the design-driven contribution process has the
+following advantages:
+
+* By writing a design doc, the feature gets more attention. During the
+ design review, feedback from various sides can be collected, which
+ likely leads to improvements of the feature.
+* Once a design was approved by the
+ link:dev-processes.html#steering-committee[steering committee], the
+ contributor can be almost certain that the feature will be accepted.
+ Hence, there is only a low risk to invest into implementing a feature
+ and see it being rejected later during the code review, as it can
+ happen with the lightweight contribution process.
GERRIT
------
diff --git a/Documentation/dev-design-doc-template.txt b/Documentation/dev-design-doc-template.txt
new file mode 100644
index 0000000..c05b778
--- /dev/null
+++ b/Documentation/dev-design-doc-template.txt
@@ -0,0 +1,54 @@
+= Gerrit Code Review - ${title}
+
+[[objective]]
+== Objective
+
+In a few sentences, describe the key system objectives. Define the
+goals and non-goals.
+
+[[background]]
+== Background
+
+Stuff one needs to know to understand this doc (e.g. motivating
+examples, previous versions and problems, links to related
+changes/design docs, etc.
+
+Note: this is background; do not write about your design or ideas to
+solve problems here.
+
+[[overview]]
+== Overview
+
+High-level overview; put details in the next section and background in
+the previous section. Should be understandable by engineers that are
+not working on Gerrit.
+
+[[detailed-design]]
+== Detailed Design
+
+How does the overall design work? Details about the algorithms,
+storage format, APIs, etc., should be included here.
+
+It is ok for this to lack in detail at first for initial review.
+
+[[alternatives-considered]]
+== Alternatives Considered
+
+You may need to describe what you did not do or why simpler approaches
+don't work. Mention other things to watch out for (if any).
+
+[[implemenation-plan]]
+== Implementation Plan
+
+If known, say who is driving the implementation, for when the
+implementation is planned and which priority it has for you.
+
+It is possible to contribute designs without having resources to do the
+implementation. In this case, say so here.
+
+GERRIT
+------
+Part of link:index.html[Gerrit Code Review]
+
+SEARCHBOX
+---------
diff --git a/Documentation/dev-design-docs.txt b/Documentation/dev-design-docs.txt
new file mode 100644
index 0000000..8cc7e81
--- /dev/null
+++ b/Documentation/dev-design-docs.txt
@@ -0,0 +1,62 @@
+= 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.
+
+[[propose]]
+== How to propose a new design?
+
+To propose a new design, add a `design-${title}.txt` file to this
+folder and push it as change for review. The design doc should follow
+the structure of the link:dev-design-doc-template.html[design doc
+template] and the change should be marked with the hashtag
+`design-doc`.
+
+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.
+
+Changes with new design docs 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 design is approved and submitted the implementation
+may start immediately.
+
+Within the 10 calendar days time frame, the contributor should hear back
+from the link:dev-processes.html#steering-committee[steering committee]
+whether the proposed feature is in scope of the project and if it can
+be accepted.
+
+In order to be accepted/submitted, it is not necessary that the design
+doc fully specifies all the details, but the idea of the feature and
+how it fits into Gerrit should be sufficiently clear (judged by the
+steering committee). Contributors are expected to keep the design doc
+updated and fill in gaps while they go forward with the implementation.
+
+[[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 `gerrit` repository with the following
+ query: `hashtag:design-doc`
+
+GERRIT
+------
+Part of link:index.html[Gerrit Code Review]
+
+SEARCHBOX
+---------
diff --git a/Documentation/dev-processes.txt b/Documentation/dev-processes.txt
index b25d425..9415a43 100644
--- a/Documentation/dev-processes.txt
+++ b/Documentation/dev-processes.txt
@@ -9,12 +9,16 @@
* Gerrit core (the `gerrit` project) and the core plugins
* defining the project vision and the project scope
* maintaining a roadmap, a release plan and a prioritized backlog
+* ensuring timely design reviews
* ensuring that new features are compatible with the project vision and
- are well aligned with other features
-* vetoing new features
+ are well aligned with other features (give feedback on new
+ link:dev-design-docs.html[design docs] within 14 calendar days)
+* approving/rejecting link:dev-design-docs.html[designs], vetoing new
+ features
* accepting new plugins as core plugins
* making changes to the project governance process and the
- link:dev-contributing.html[contribution process]
+ link:dev-contributing.html#contribution-processes[contribution
+ processes]
The steering committee has 5 members:
@@ -66,6 +70,11 @@
See link:dev-contributing.html[here].
+[[design-doc-review]]
+== Design Doc Review
+
+See link:dev-design-docs.html#review[here].
+
[[dev-in-stable-branches]]
== Development in stable branches
diff --git a/Documentation/dev-roles.txt b/Documentation/dev-roles.txt
index cb5e7c5..a093073 100644
--- a/Documentation/dev-roles.txt
+++ b/Documentation/dev-roles.txt
@@ -54,6 +54,11 @@
see below)
* file issues in the link:https://bugs.chromium.org/p/gerrit/issues/list[
issue tracker] and comment on existing issues
+* support the
+ link:dev-processes.html#design-driven-contribution-process[
+ design-driven contribution process] by reviewing incoming
+ link:dev-design-docs.html[design docs] and raising concerns during
+ the design review
Supporters who want to engage further can get additional privileges
on request (ask for it on the
@@ -91,6 +96,9 @@
* code cleanups
* documentation updates
* release notes updates
+* propose link:#dev-design-docs[design docs] as part of the
+ link:dev-contributing.html#design-driven-contribution-process[
+ design-driven contribution process]
* scripts which are of interest to the community
Contributors have all the permissions that link:#supporter[supporters]
@@ -107,8 +115,9 @@
Being member of the `gerrit-verifiers` group includes further
permissions (see link:#supporter[supporter] section above).
-It's highly appreciated if contributors engage in code reviews and
-mailing list discussions.
+It's highly appreciated if contributors engage in code reviews,
+link:dev-design-docs.html#review[design reviews] and mailing list
+discussions.
Contributors may also be invited to join the Gerrit hackathons which
happen regularly (e.g. twice a year). Hackathons are announced on the
@@ -151,6 +160,11 @@
* reviewing changes
* mailing list discussions and support
* bug fixing and bug triaging
+* supporting the
+ link:dev-processes.html#design-driven-contribution-process[
+ design-driven contribution process] by reviewing incoming
+ link:dev-design-docs.html[design docs] and raising concerns during
+ the design review
* doing releases (see link#release-manager[release manager])
Maintainers can:
@@ -160,9 +174,9 @@
ignored if there is a good reason, in this case the reason should be
clearly communicated on the change
* submit changes
-* block submission of changes if they disagree with a feature or with
- how it is being implemented (vote `-2` on the `Code-Review` label),
- but their vote can be overruled by the steering committee, see
+* block submission of changes if they disagree with how a feature is
+ being implemented (vote `-2` on the `Code-Review` label), but their
+ vote can be overruled by the steering committee, see
link:dev-processes.html#project-governance[Project Governance]
* nominate new maintainers and vote on nominations (see below)
* administrate the link:https://groups.google.com/d/forum/repo-discuss[
