Gerrit Code Review - A Quick Introduction

Obviously the first thing we need to do is get the source that we’re going to be modifying. As with any git project you do this by cloning the central repository that Gerrit is hosting. e.g.

Then we need to make our actual change and commit it locally. Gerrit doesn’t really change anything here, this is just the standard editing and git. While not strictly required, it’s best to include a Change-Id in your commit message so that Gerrit can link together different versions of the same change being reviewed. Gerrit contains a standard Change-Id commit-msg hook that will generate a unique Change-Id when you commit. If you don’t do this then Gerrit will generate a Change-Id when you push your change for review. But because you don’t have the Change-Id in your commit message you’ll need to manually copy it in if you need to upload another version of your change. Because of this it’s best to just install the hook and forget about it.

Once you’ve made your change and committed it locally it’s time to push it to Gerrit so that it can be reviewed. This is done with a git push to the Gerrit server. Since we cloned our local repository directly from Gerrit it is the origin so we don’t have to redefine the remote.

The only different thing about this is the refs/for/master branch. This is a magic branch that creates reviews that target the master branch. For every branch Gerrit tracks there is a magic refs/for/<branch_name> that you push to to create reviews.

In the output of this command you’ll notice that there is a link to the HTTP interface of the Gerrit server we just pushed to. This is the web interface where we will review this commit. Let’s follow that link and see what we get.

This is the Gerrit code review screen where someone will come to review the change. There isn’t too much to see here yet, you can look at the diff of your change, add some comments explaining what you did and why, you may even add a list of people that should review the change.

Reviewers can find changes that they want to review in any number of ways. Gerrit has a capable search that allows project leaders (or anyone else) to find changes that need to be reviewed. Users can also setup watches on Gerrit projects with a search expression, this causes Gerrit to notify them of matching changes. So adding a reviewer when creating a review is just a recommendation.

At this point the change is available for review and we need to switch roles to continue following the change. Now let’s pretend we’re the reviewer.

The reviewer’s life starts at the code review screen shown above. He can get here in a number of ways, but for some reason they’ve decided to review this change. Of particular note on this screen are the two "Need" lines:

Gerrit’s default work-flow requires two checks before a change is accepted. Code-Review is someone looking at the code, ensuring it meets the project guidelines, intent etc. Verifying is checking that the code actually compiles, unit tests pass etc. Verification is usually done by an automated build server rather than a person. There is even a Gerrit Trigger Jenkins Plugin that will automatically build each uploaded change and update the verified score accordingly.

It is important to note that Code-Review and Verification are different permissions in Gerrit, allowing these tasks to be separated. For example, an automated process would have rights to verify but not to code-review.

Since we are the code reviewer, we’re going to review the code. To do this we can view it within the Gerrit web interface as either a unified or side-by-side diff by selecting the appropriate option. In the example below we’ve selected the side-by-side view. In either of these views you can add inline comments by double clicking on the line (or single click the line number) that you want to comment on. Also you can add file comment by double clicking anywhere (not just on the "Patch Set" words) in the table header or single clicking on the icon in the line-number column header. Once published these comments are viewable to all, allowing discussion of the change to take place.

Code reviewers end up spending a lot of time navigating these screens, looking at and commenting on these changes. To make this as efficient as possible Gerrit has keyboard shortcuts for most operations (and even some operations that are only accessible via the hot-keys). At any time you can hit the ? key to see the keyboard shortcuts.

Once we’ve looked over the changes we need to complete reviewing the submission. To do this we click the Review button on the change screen where we started. This allows us to enter a Code Review label and message.

The label that the reviewer selects determines what can happen next. The +1 and -1 level are just an opinion where as the +2 and -2 levels are allowing or blocking the change. In order for a change to be accepted it must have at least one +2 and no -2 votes. Although these are numeric values, they in no way accumulate; two +1s do not equate to a +2.

Regardless of what label is selected, once the Publish Comments button has been clicked, the cover message and any comments on the files become visible to all users.

In this case the change was not accepted so the creator needs to rework it. So let’s switch roles back to the creator where we started.

As long as we set up the Change-Id commit-msg hook before we uploaded the change, re-working it is easy. All we need to do to upload a re-worked change is to push another commit that has the same Change-Id in the message. Since the hook added a Change-ID in our initial commit we can simply checkout and then amend that commit. Then push it to Gerrit in the same way as we did to create the review. E.g.

Note that the output is slightly different this time around. We don’t get told about a new review because we’re adding to an existing review. Having uploaded the reworked commit we can go back into the Gerrit web interface and look at our change.

If you look closely you’ll notice that there are now two patch sets associated with this change, the initial submission and the rework. Rather than repeating ourselves lets assume that this time around the patch is given a +2 score by the code reviewer.

With Gerrit’s default work-flow there are two sign-offs, code review and verify. Verifying means checking that the change actually works. This would typically be checking that the code compiles, unit tests pass and similar checks. Really a project can decide how much or little they want to do here. It’s also worth noting that this is only Gerrit’s default work-flow, the verify check can actually be removed or others added.

As mentioned in the code review section, verification is typically an automated process using the Gerrit Trigger Jenkins Plugin or similar. But there are times when the code needs to be manually verified, or the reviewer needs to check that something actually works or how it works. Sometimes it’s just nice to work through the code in a development environment rather than the web interface. All of these involve someone needing to get the change into their development environment. Gerrit makes this process easy by exposing each change as a git branch. So all the reviewers need to do is fetch and checkout that branch from Gerrit and they will have the change.

We don’t even need to think about it that hard, if you look at the earlier screen shots of the Gerrit Code Review Screen you’ll notice a download command. All we need to do to get the change is copy paste this command and run it in our Gerrit checkout.

Easy as that, we now have the change in our working copy to play with. You might be interested in what the numbers of the refspec mean.

For simplicity we’re just going to manually verify the change. The Verifier may be the same person as the code reviewer or a different person entirely. It really depends on the size of the project and what works. If you have Verify permission then when you click the Review button in the Gerrit web interface you’ll be presented with a verify score.

Unlike the code review the verify check doesn’t have a +2 or -2 level, it’s either a pass or fail so all we need for the change to be submitted is a +1 score (and no -1’s).

You might have noticed that in the verify screen shot there are two buttons for submitting the score Publish Comments and Publish and Submit. The publish and submit button is always visible, but will only work if the change meets the criteria for being submitted (I.e. has been both verified and code reviewed). So it’s a convenience to be able to post review scores as well as submitting the change by clicking a single button. If you choose just to publish comments at this point then the score will be stored but the change won’t yet be accepted into the code base. In this case there will be a Submit Patch Set X button on the main screen. Just as Code-Review and Verify are different operations that can be done by different users, Submission is a third operation that can be limited down to another group of users.

Clicking the Publish and Submit or Submit Patch Set X button will merge the change into the main part of the repository so that it becomes an accepted part of the project. After this anyone fetching the git repository will receive this change as a part of the master branch.