A code review process is based on a process in which people can suggest, review, update and accept changes.

Once a change is accepted, people with the correct permission can accept it.

The involved people are typically decided into two groups: * contributors - people with the permission to create, review and update changes * committers - people with the additional permission to accept changes

A code review process can be implemented without any tool support. But it is typically more efficient, if a structured code review system is used.

Using a code review system, allows to perform an automated test build of the proposed merge. Continuous integration tools like Jenkins or Hudson can integrate with the review system to find compile errors and to run a test suite.

In general a structured code review process has the following advantages:

For an efficient process, the code review should be conducted in a supportive environment where constructive feedback is given to enhance the change.

Gerrit is a code review system developed for the Git version control system. It is a web based code review system, facilitating online code reviews for projects. Gerrit is a Git server which adds a fine grained access control system and a code review system and workflow.

The user interface of Gerrit is based on Google Web Toolkit. Its uses JGit library to provide the Git functionality.

A developer can use Gerrit to suggest a change. Other developers can review the change and suggest improvements. If a Gerrit change needs improvement, it is possible to update it with a new commit. Once the suggested changes are accepted, they can be merged to the target branch of the Git repository via the Gerrit user interface.

Gerrit makes code reviews easier by showing changes in a side-by-side display. It also supports to display the change as a unified diff which is often easier to read on smaller screens.

A reviewer can add comments to every single line changed.

Gerrit is licensed under the Apache 2.0 license.

The Gerrit review system uses the term change, to define a code review / review request. Each change is based on one commit.

Gerrit can prevent users from pushing directly to the Git repository. If you push to Gerrit, you use a certain path ( ref specification) which tells Gerrit that you want to create a change. This push ref specification is refs/for/master if the target of the change under review is the master branch. You can also push to refs/for/xyz to put a commit into the review queue for the xyz branch.

If you push to this ref specification, Gerrit creates a new change or makes an update of an existing one. Gerrit uses the Change-Id information in the commit message to identify if the push is a new commit or an update of an existing change.

A change consists of one or more patch sets which are used to improve the first proposal based on review comments. One patch set corresponds to one Git commit.

It is still possible to bypass code review by pushing directly to refs/heads/master if sufficient rights have been granted.

Gerrit supports different categories (also known as labels) for review feedback. In its default configuration it supports the Code-Review category.

In typical installations also the Verified category is installed.

The Verified category typically means you were able to build and test the change introduced with the Gerrit change. Typically, this is done by an automated process such as a Jenkins / Hudson build server.

The "Code-Review" category is typically used to vote on the quality of the implementation, code style, code conformity. It also indicates that the change is in accordance with the standards desired by the project.

Committers and contributors can vote in these categories.

The rules for voting in Gerrit is:

Typically Gerrit instances uses the Verified and the Code-Review category.

If you did some manual testing and the code works as you desire then it is good to +1 in the "Verified" category. Or give -1 if it failed some of your use cases that must be resolved in order to merge. Otherwise, leave it as 0, if you did not test the code.

Non-committers of the project can vote with -1 and +1 to indicate an opinion in either way. But ultimately it is up to the decision of those with +2 power to make the overall decision. You may want to -2 vote to block the submission of the code. Or vote +2 to indicate that you approve that the contribution is merged into the Git repository.

There is also a special refs/drafts/master refspec which you can use to push changes to for private review before publishing them to all developers.

This is useful if your work is in progress and not ready for public reviews. You can also CC specific people to review this private change. Once it is ready for public review there is a Publish button to convert the draft into a change review.

A server can also be the local machine, for example, if you want to test Gerrit.

See https://github.com/GerritCodeReview/docker-gerrit

The following describes a typical Gerrit workflow of you as a developer using Gerrit.

Afterwards you perform the following steps.

Repeat the last three steps until the patch is finally accepted and merged into the codebase (or until the change is completely rejected). Finally you can delete your local branch.

In the Gerrit scenario amending a commit is used to update the Gerrit change request. Using the amend operation on a published commit is usually discouraged in Git, in Gerrit it is the normal process.

The Gerrit review system is based on the assumption that each commit is reviewed separately. At GitHub, a complete branch is reviewed and merging with the pull request.

You require a valid Gerrit user to work with Gerrit. In your test installation, you create your own users.

Login to your Gerrit installation. Assuming that you installed it on your local machine using the default values, you can access it via the following URL:

The first user to login automatically gets the administrator status.

If you want to use SSH you have to upload your SSH key. If you prefer to use HTTPS, skip this step and go to HTTPS setup.

From the user drop down menu select Settings and select SSH Keys to upload your public SSH key.

Based on your SSH key you are now able to exchange data with the Gerrit server.

Select Profile to assign a Username to your user.

You can also enter a password for HTTPS access.

Click on one change request to see the details of the Gerrit change request. Click on the commit message of the file name (highlighted in the screenshot) to see the changes in the file.

You can double-click on a line to comment on the change.

Clicking on Up to change brings you back to the change.

Gerrit allows you to review the commit message, which appears at the top of the file list. To understand the history of the repository it is important to provide a good commit message.

Click on Reply button to give feedback on the change.

You can give a summary of your feedback and return a review number between -2 and +2 (if you are a committer) or between -1 and +1 (if you are not a committer). If you vote -1 or -2, you respectively indicate that the patch still requires rework or that you disagree with the suggested change. See Voting in Gerrit for details of the default voting rules.

If the review process has resulted review comments explaining how to improve the proposed patch, the author of the patch (or someone else) can adjust the patch. The developer amends the commit in his local repository and pushes the improved commit to Gerrit. He can also adjust the commit message while amending the commit.

As the developer amends the commit, the same Change-Id is used and the Gerrit review system identifies the change as update of the existing change.

The Git Staging view allows amending the last commit by clicking the amend button shown in the screenshot.

Once the change has reached the required quality, the reviewer can give a +2 evaluation of the change.

Depending on the settings of the Gerrit repository, the Gerrit review might have to be rebased. If conflicts happen during this rebase operation, you can trigger this rebase directly from the web interface. If a change is rebased, it needs to be reviewed again.

Afterwards a developer with commit rights can submit the change. This is typically done by the same committer who voted +2. This may require that the corresponding commit is based on the current origin/master branch. This depends on the Gerrit configuration for the project. The Gerrit UI allows the committer or contributor to rebase the change onto origin/master if no conflicts occur.

Press the "?" key in the Gerrit web user interface to see the actions you can trigger via shortcuts. The available shortcuts depend on there you are in the user interface.

The available shortcuts are different, depending on the page you are.

It is possible to fetch the changes from the Gerrit review into another local Git repository. The Gerrit page lists the commands for downloading the change. This is depicted in the following screenshot.

After fetching a change, the developer can adjust the change and amend the commit. If he pushes it to Gerrit, the change is updated. Such a procedure should be coordinated by the author of the original change to avoid that two developers do the same work.

When working with many projects, it is often easier to right-click on the repository instead and access Fetch from Gerrit from there. You can paste the change’s number (shown in the change’s URL) and use Ctrl+Space to expand the change number to the list of patch sets. Select the one you want to download and fetch it into a new local branch. Afterwards you can test the changes in isolation.

You can also edit directly in Gerrit. Press the edit button for this.

Afterwards select the file or the commit message you want to edit. Press save and close once you are done. After you are done with all your edits, press the Publish Edit.

If you try to push a commit which contains the same ChangeId as a predecessor commit, Gerrit rejects it and responds with the error message: "squash commits first".

In this case you probably forgot to amend the existing commit and used the same Gerrit Change-ID. This is depicted in the following graphic.

In this case you need to squash the commits. This results in a new commit which can be pushed to Gerrit. As you use the same Change-ID this pushed commit updates the Gerrit review. In the following diagram the "Commit 2'" is the result of squashing "Commit 2" and "Commit 3" into one commit.

An easy solution to handle this is, to do a soft reset in Git to the previous commit and commit the change files again, this time with the amend option. If you really intended to create two commits you need to generate a new changeId in the second commit which was rejected.

The submit step may fail due to merge conflicts, depending on the Gerrit project configuration.

The easiest way to do so is via the Rebase button in the Gerrit web interface, if there are no conflicts.

In case you have to resolve merge conflicts you have to do this locally and push an updated commit. The steps required to solve a merge conflict are:

This creates a new patch set for the change. The new patch set has to pass the code review again. Submit the new patch set change to merge it into the master branch.

You get this error message, if you try to submit a commit which would result in a non-fast forward merge. The Gerrit service is sometimes configured with the setting to allow only fast-forward merges.

In this case the pushed commit is not based on the current tip of the remote branch. This problem is depicted in the following graphic.

The solution is to rebase your commit onto origin/master. Afterwards you push the commit again to Gerrit.

See non-fast forward for details.

If you create a series of dependent commits, it might happen that one of the commits is rejected during the review process.

In this case, you cannot merge the other commits as they still have a dependency to the "bad" commit.

During the review process commit 2 are rejected. The commit 3 and commit 4 are still good and do not depend on the changes in commit 2.

The solution is to use interactive rebase to skip the bad commit.

See Gerrit error message for more error messages and their solutions.

It is typically a good approach to fix something really simple as the first step. Search for a few warning messages in the code, or a typo in the documentation, and prepare a fix for it.

Once you get familiar with the contribution process start contributing something more difficult.

A Gerrit change (== one commit) should address only one issue.

Avoid going "off topic" with your patches. If you would like to clean up some code, or fix something out of the scope of your patch, create additional patches. This will make your patches more concise, easier to review and easier to revert if something go wrong.

In many open source projects smaller patches tend to be reviewed faster and merged faster as it is easier for the committer to review. With this in mind, try to break your contributions into small concise Gerrit changes. It is more likely that these get reviewed and accepted.

It also helps to reach a clean history. Imagine you are chasing a bug in code which was introduced 2 years back. If the history is built from small concise commits, it is easier to find the commit which introduced the problem and understand the motivation why it was done in the way it was implemented.

Most project handles the required commit message a bit differently. For example, the Eclipse Platform project prefers the following format:

The text in the header must match the title in Bugzilla. The Eclipse Git tooling complains about commit headers longer than 80, but you can ignore this warning. For example the following is a valid commit message for the Eclipse platform project. The description in the body of the commit message can take as many lines as necessary and should be descriptive of what is going into the patch. For more complex patches you should provide implementation details and enough notes to allow the reviewer to understand what your fix provides.

It is important to explain in the commit body, why the change was done. Also explain why you have chosen a certain implementation method, if there was something special about it.

In some projects the source file contains a copyright header. If you modify the file you should also update the copyright header. Different project might use different standards here. Have a look at existing commits and the header in the existing files and try to adapt the style preferred by the existing developers.

Most Eclipse projects to not required to update the copyright header. Optionally you can also add yourself to the copyright with a reference to the bug and update the copyright header with the last modified year. The following listing shows an example for this standard.

The above file was created in 2008 and last modified in 2015. It was originally created by employees of IBM and also modified by John Doe and he fixed Bug 429728 with it. The additional entry in the Contributors section is typically considered optional, but this depends on the individual project.

If you work for an organization the Foundation recommends adding the organization name in parentheses. See: Copyright info from eclipse.org. For example:`John Doe (vogella GmbH) John.Doe@fake.com - Bug 429728 - Fixed compiler warnings`

If you add a new file don’t forget to add the copyright header using the project’s license. For new files, list "yourself and others" instead of "IBM and others" in the first line.

If you fix several bugs in the same file, you should list the bug separately as in the following example listing. In case you find yourself changing the same file over and over again, you could also use "ongoing maintenance" instead of listing every bug number.

In most cases you should avoid putting in the bug number into the source code (except the header). Only if you have to implement a workaround for an existing bug, you should add a reference in the source to this bug.

The best way to get your contribution accepted is to stay polite and to follow the guidance of the existing committers. For the first few contributions it is best to stay with the current processes and guidelines. If you continue to contribute, you will gain more trust and responsibility and you may be able to improve also the processes used by the project.

Typically open source projects dislike if you re-format unchanged lines, as this makes the review process much harder. Avoid pressing the Format source code shortcut in your editor. Instead, only select the changes lines and then press the format source code shortcut (this is also an auto-save preference).

Unnecessary format changes makes it really hard to review a Gerrit change. The following screenshot shows a file which was reformatted, it is unnecessary hard for the reviewer to find the real change.

Typically projects dislike unnecessary whitespace in the contributed code. Ensure that you remove trailing whitespaces from your contributed code.

Unfortunately lots of project have unnecessary whitespace included in the source code, most committers also don’t like if you remove them as it changes the history.

For most projects it is OK to push an initial (unfinished) implementation concept to Gerrit and to ask for feedback.

Mark unfinished commits with [RFC] (request for comments) or [WIP] (work in progress) in the commit message header to avoid frustrating reviewers who typically want to know if the change is considered to be ready by the author or not.

Some project uses additional validation plug-ins. For example the Eclipse foundation uses a server-side Gerrit plugin which checks for conformity with the CLA. When you push a change to Gerrit this plugin verifies if your contribution passes all the CLA requirements from the Eclipse foundation.

This means that the author field must be a valid Eclipse user. If the author is not a committer it requires that the author also "Sign-off" their contribution. Eclipse Git provides a preference to always sign-off changes.

See: Wiki for Git contributions

If everything works perfectly, the developers of the project you are contributing to will accept your contribution and help you to solve all your open questions.

If you don’t get feedback there are different possible reasons: maybe all committers are busy or in vacation. Or your change is extremely large (hard to review) or it ignores all the rules explained in the project’s contributor guide.

If your contribution is ignored, feel free to ask in the Bug report for feedback or to send email to the project mailing list.

Don’t get frustrated by negative feedback, as the collaboration almost always results in a better commit that benefits everyone.