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-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[
