Contributor License Agreement

In order to contribute to Gerrit a Contributor License Agreement must be completed before contributions are accepted.

Contribution Processes

The Gerrit project offers two contribution processes:

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 maintainers review them adhoc.

For large/complex features, it is required to specify the feature in a design document before starting implementation, as per the design-driven contribution process.

If contributors choose the lightweight contribution process but the feature is found to be large or complex, maintainers can require that the design-driven contribution process be followed instead.

If you are in doubt which process is right for you, consult the repo-discuss mailing list.

These contribution processes apply to everyone who contributes code to the Gerrit project. Maintainers 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 mentor support. A mentor helps with timely code reviews and technical guidance, though the implementation itself is still the responsibility of the contributor.

Quick Comparison

Lightweight Contribution Process Design-Driven Contribution Process

Overhead

low (write good commit message, address review comments)

high (write design doc 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 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

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 design-driven contribution process is required.

To start contributing to Gerrit, upload your git commit for review to the gerrit-review.googlesource.com Gerrit server. Review these guidelines before submitting your change. You can view pending contributions here.

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

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 design doc and get it approved by the steering committee before starting the implementation.

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

  • A contributor proposes a new feature by uploading a change with a design doc.

  • The design doc is 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 30 calendar days the contributor should hear back from the 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 steering committee.

  • After the design is approved, it is implemented by pushing changes for review, see the 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 mentor if requested (see 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 steering committee, 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 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

For features for which a design has been approved (see design-driven contribution process), contributors can gain the support of a mentor if they are committed to implement the feature.

A mentor 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 maintainer.

Mentors are assigned by the steering committee. To gain a mentor, ask for a mentor in the Implementation Plan 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.

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.

Part of Gerrit Code Review