Documentation/dev-contributing.txt

:linkattrs:
= Gerrit Code Review - Contributing

[[prerequisites]]
== Prerequisites

In order to contribute to Gerrit and have contributions accepted by
the server, you must with your Google account:

* complete a link:dev-cla.html[Contributor License Agreement,role=external,window=_blank]
* subscribe to the
  link:https://groups.google.com/d/forum/repo-discuss[repo-discuss,role=external,window=_blank]
  mailing list

[[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,role=external,window=_blank]
review them adhoc.

For large/complex features, it is required to specify the feature in a
link:dev-design-docs.html[design document,role=external,window=_blank] before
starting implementation, as per the
link:#design-driven-contribution-process[design-driven contribution process].

If link:dev-roles.html#contributor[contributors,role=external,window=_blank]
choose the lightweight contribution process but the feature is found to be 
large or complex, link:dev-roles.html#maintainer[maintainers,role=external,window=_blank]
can require that the design-driven contribution process be followed 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,role=external,window=_blank]
mailing list.

These contribution processes apply to everyone who contributes code to
the Gerrit project. link:dev-roles.html#maintainer[
Maintainers,role=external,window=_blank] are also considered contributors
when they contribute code.

If a new feature is large or complex, it is often difficult to find a
maintainer who can take the time that is needed for a thorough review. This
can result in unpredictably long waiting times before the changes are
submitted. To avoid that, contributors can ask for link:#mentorship[mentor support].
A mentor helps with timely code reviews and technical guidance, though the 
implementation itself is still the responsibility of the contributor.

[[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,role=external,window=_blank]
and get it approved)
|Technical Guidance|by reviewer|during the design review and by
reviewer/mentor
|Review  |adhoc (when reviewer is available)|by a dedicated mentor (if
a link:#mentorship[mentor] was assigned)
|Caveats |features may get vetoed after the implementation was already
done, maintainers may require the design-driven contribution process
be followed if a change gets too complex/large|design doc must stay open
for a minimum of 10 calendar days, a mentor may not be available
immediately
|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.

To start contributing to Gerrit, upload your git commit for review to the
link:https://gerrit-review.googlesource.com/[gerrit-review.googlesource.com,
role=external,window=_blank] Gerrit server. Review these link:dev-crafting-changes.html[
guidelines,role=external,window=_blank] before submitting your change.  You can
view pending contributions link:https://gerrit-review.googlesource.com/#/q/status:open+project:gerrit[here,role=external,window=_blank].

Depending on the size of that list it might take a while for
your change to get reviewed. 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`.

Finally, the quicker you respond to the comments of your reviewers, the
quicker your change can be 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.

A new feature or API extension, even if small, can incur a long-time
maintenance and support burden and should be left pending for 24 hours
to give maintainers in all time zones a chance to evaluate the change.

[[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 functionality and scope before spending too much time on
  implementation
* ensure that they are in line with Gerrit's project scope and vision
* ensure that they are well aligned with other features
* consider 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,role=external,window=_blank]
and get it approved by the
link:dev-processes.html#steering-committee[steering committee,role=external,window=_blank]
before starting the implementation.

The design-driven contribution process consists of the following steps:

* A link:dev-roles.html#contributor[contributor,role=external,window=_blank]
  link:dev-design-docs.html#propose[proposes,role=external,window=_blank] a new
  feature by uploading a change with a
  link:dev-design-docs.html[design doc,role=external,window=_blank].
* The design doc is link:dev-design-docs.html#review[reviewed,role=external,window=_blank]
  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 30 calendar days the contributor should hear back from the
  link:dev-processes.html#steering-committee[steering committee,role=external,window=_blank]
  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,role=external,window=_blank].
* After the design is approved, it is implemented by pushing
  changes for review, see the 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 for its completion.
  Others from the Gerrit community are usually welcome to help.

The design doc does not need to fully specify each detail of the feature,
but its concept and how it fits into Gerrit should be sufficiently clear,
as 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 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 is not yet approved. Another way to demonstrate the design can be
mocking screenshots in the doc.

By approving a design, the steering committee commits to:

* Accepting the feature when it is implemented.
* Supporting the feature by assigning a link:dev-roles.html#mentor[
  mentor,role=external,window=_blank] if requested (see link:#mentorship[mentorship]).

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 is approved by the
  link:dev-processes.html#steering-committee[steering committee,role=external,window=_blank],
  the contributor can be almost certain that the feature will be accepted.
  Hence, there little risk of the feature being rejected later in code review,
  as can occur with the lightweight contribution process.
* The contributor can link:#mentorship[get a dedicated mentor assigned]
  who provides timely reviews and serves as a contact person for
  technical questions and discussing details of the design.

[[mentorship]]
== Mentorship

For features for which a link:dev-design-docs.html[design,role=external,window=_blank]
has been approved (see link:#design-driven-contribution-process[design-driven
contribution process]), contributors can gain the support of a mentor
if they are committed to implement the feature.

A link:dev-roles.html#mentor[mentor,role=external,window=_blank] helps with:

* doing timely reviews
* providing technical guidance during code reviews
* discussing details of the design
* ensuring that the quality standards are met (well documented,
  sufficient test coverage, backwards compatible etc.)

A feature can have more than one mentor. To be able to deliver the
promised support, at least one of the mentors must be a
link:dev-roles.html#maintainer[maintainer,role=external,window=_blank].

Mentors are assigned by the link:dev-processes.html#steering-committee[
steering committee,role=external,window=_blank]. To gain a mentor, ask for a
mentor in the link:dev-design-doc-template.html#implementation-plan[Implementation
Plan,role=external,window=_blank] section of the design doc or ask the steering
committee after the design has been approved.

Mentors may not be available immediately. In this case, the steering
committee should include the approved feature into the roadmap or
prioritize it in the backlog. This way, it is transparent for the
contributor when they can expect to be able to work on the feature with
mentor support.

Once the implementation phase starts, the contributor is expected to do
the implementation in a timely manner.

For every mentorship, the end must be clearly defined. The design doc
must specify:

* a maximum time frame for the mentorship, after which the mentorship
  automatically ends, even if the feature is not done yet
* done criteria that define when the feature is done and the mentorship
  ends

If a feature implementation is not completed in time and no contributors
can commit to finishing the implementation, changes that have already been
submitted for the feature may be reverted to avoid unused or half-finished
code in the code base. In these circumstances, the steering committee
determines how to proceed.

[[esc-dd-evaluation]]
== How the ESC evaluates design documents
This section describes how the ESC evaluates design documents. It’s
meant as a guideline rather than being prescriptive for both ESC
members and contributors.

=== General Process
As part of the design process, the ESC makes a final decision if a
design gets to be implemented. If there are multiple alternative
solutions, the ESC will decide which solution can be implemented.

The ESC should wait until all contributors had the chance to
voice their opinion in review comments or by proposing alternative
solutions. Due to the infrequent ESC meetings (every 2-4 weeks)
the ESC might discuss documents in cases where the discussion is
already advanced far enough, but not make a decision yet. In this
case, contributors can still voice concerns or discuss alternatives.
The decision can be at the next meeting or via email in between
meetings.

=== Evaluation
Product/Vision fit

Q: `Do we believe this feature belongs to Gerrit Code Review use-cases?`

* Yes: Customizable dashboards
* No: UI for managing an LDAP server

Q: `Is the proposed solution aligned with Gerrit’s vision?`

* Yes: Showing comments of older patch sets in newer patch sets to
  keep track (core code review)
* No: Implement a bug tracker in Gerrit (not core code review).

=== Impact
Q: `Will the new feature have a measurable, positive impact?`

* Yes: Increased productivity, faster/smoother workflow, etc.
* Yes: Better latency, more reliable system.
* No: Unclear impact or lacking metrics to measure.

=== Complexity
Q: `Can we support/maintain this feature once it is in Gerrit?`

* Yes: Code will fit into codebase, be well tested, easy to
  understand.
* No: Will add code or a workflow that is hard to understand
  and easy to misinterpret.

Q: `Is the proposed feature or rework adding unnecessary complexity?`

* Yes: Adding a dependency on a well-supported library.
* No: Adding a dependency on a library that is not widely used
  or not actively maintained.

=== Core vs. Plugin decision
Q: `Would this fit better in a plugin?`

* Yes: The proposed feature or rework is an implementation (e.g. Lucene
  is an index implementation) of a generic concept that others
  might want to implement differently.
* Yes: The proposed feature or rework is very specific to a custom setup.
* No: The proposed feature or rework is applicable to a wider user
  base.
* No: The proposed feature or rework is a `core code review feature`.

=== Commitment
Q: `Is someone willing to implement it?` (this question is
especially important when reviewers propose alternative designs
to the author’s own solution).

* Yes: The author or someone else commits to implementing the
  proposed solution.
* Yes: If a mentorship is required, a mentor is willing to help.
* No: Unclear ownership, mentorship or implementation plan.

=== Community
Q: `If in doubt, is there a substantial benefit to a long-standing
community member with many users?`

* The community shapes the future of Gerrit as a product. In
  cases of doubt, the ESC can be more generous with long-standing
  community members compared to `drive-by` contributions.

GERRIT
------
Part of link:index.html[Gerrit Code Review]

SEARCHBOX
---------