commit 099a5ece624dc527d1d394d58b19ca9bce33bf02
author Edwin Kempin <ekempin@google.com> Thu Apr 25 16:15:14 2019 +0200
committer Marco Miller <marco.miller@ericsson.com> Wed May 15 17:17:48 2019 -0400
tree 5490a9fb8b29d996e9e81824cea909d22a275531
parent 8189f32d580ead2dea0648a22c646c045de06fca

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