opendev/gerrit
Code Issues Proposed changes

Document design-driven contribution process

Browse Source 
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
This commit is contained in:
Edwin Kempin
2019-04-25 16:15:14 +02:00
committed by Marco Miller
parent 8189f32d58
commit 099a5ece62
6 changed files with 315 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
Documentation/dev-community.txt
View File

@@ -16,7 +16,10 @@ link:dev-cla.html[contributor's agreement] on file with the project.
* 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 @@ link:dev-cla.html[contributor's agreement] on file with the project.
[[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]

179
Documentation/dev-contributing.txt
View File

@@ -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 @@ link:https://gerrit-review.googlesource.com/#/q/status:open+project:gerrit[here]
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
------

54
Documentation/dev-design-doc-template.txt Normal file
View File

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

62
Documentation/dev-design-docs.txt Normal file
View File

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

15
Documentation/dev-processes.txt
View File

@@ -9,12 +9,16 @@ The Gerrit project has a steering committee that is in charge of:
* 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 @@ link:steering-committee[steering committee]).
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

24
Documentation/dev-roles.txt
View File

@@ -54,6 +54,11 @@ Supporters can:
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 @@ Contributions can be:
* 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 @@ group, which allows to:
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 @@ following tasks (but are not required to do so):
* 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 @@ Maintainers can:
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[