ITK/Gerrit/ReviewPrimer

Gerrit code reviews can be relatively straightforward, but also give the reviewer a chance to look deep into proposed changes building and testing those changes locally. This primer is intended to guide the reader through the process of a deep review of a code change.

Prerequisites

This primer assumes a working knowledge of how to build ITK. No details will be given as to how to build and test the code (but they can be found here). This primer also assumes a working knowledge of git. Please see the ITK git pages and/or git books (ProGit, Community Book, or Version Control withGit).

Also required is a Gerrit change to review. We will go through a real life code review of a change submitted to Gerrit.

Select an open change

The primary review site for Gerrit/ITK is http://review.source.kitware.com. From this page, changes may be reviewed, etc. Our review will be of Change I5e76253f: Removed unecessary commented out debugging code commited on Sept. 17, 2010. Because Gerrit is dynamic, this primer will include many screenshots, YMMV.

The screen below is from Gerrit and contains several sections of interest.

A This section gives details of the change author (Hans Johnson), project(ITK), destination branch (master), topic (removeUnnecessaryComments), dates and status.
B This section is the commit message. The standard format for a commit is a single line summary, blank line, and longer description of the change. C This section gives the details of the reviewers. A developer may request certain registered developers as reviewers for the change, and any Gerrit registered user may comment. D This section gives details on the submitted code. It provides details on how to pull the changes from Gerrit. At the bottom is a list of files changed and links to diffs.

Review steps

• Review the code in Gerrit
• Use git to pull the changes
• Build, test, review locally
• Optionally, modify the commit and push changes back into Gerrit for review
• Score the change with comments
• If the change is ready, push it into the official repository

Review the code in Gerrit

The Gerrit developers have created a very useful system for code review that includes helpful shortcuts. The available shortcuts can be accessed by pressing the '?' key.

From the change we are reviewing, press <enter> or "o" to open the diff viewer. You may also press the "Side-by-Side" link next to "Commit Message". This brings up the difference viewer.

The first file to review is the commit message. At the top of the screen are some options controlling the display of the diffs. Change to suit your tastes.

Since there is not much to see, press ] to move to the next file:

Lines 12-14 have been commented out in the change. Individual lines in the diff may be commented on by double clicking the line (when you are logged in to Gerrit). These comments are preserved in Gerrit and shown to the author and reviewers when the review is completed.

Let's comment on line 14:

Clicking "Save" when finished:

Useful navigation commands

• n Move to next diff within a file.
• p Move to previous diff within a file.
• ] Move to next file.
• [ Move to previous file.
• f Show/Hide list of files.

Use git to pull the changes

Press u or click "Up to changes" to return to the main change page.

Gerrit implements a full git server and provides hints as to how to pull this particular change. Be aware, that the hints are mainly command lines.

Gerrit allows git to use anonymous HTTP, SSH and authenticated HTTP to pull changes. The protocol is set using the radio buttons on the right hand side of the Download section of Patch Set 1. Git has several different ways to pull the changes:

• checkout Pull the change locally and set the current branch to be this change.
• pull Pull the change locally, but don't do anything else (current branch is unchanged).
• cherry-pick Pull the change and cherry-pick it into your current branch. Cherry-picking adds the changes as a commit on your current branch. NB: cherry-pick adds a commit to your current branch!
• patch Pull the changes, and apply them to the current branch, but don't commit.

In our case, let's do a checkout using anonymous HTTP (the default). Click the clipboard icon to the right of the git command to copy the proper command to the local clipboard and paste into a terminal:

git fetch http://review.source.kitware.com/p/ITK refs/changes/79/79/1 && git checkout FETCH_HEAD

If you notice my command prompt:

revelation:ITK((no branch)) blezek$

I have added a little bash magic to have the current git branch displayed in the prompt. Very helpful as a reminder to what I'm working on. The magic is:

# Git branch on the prompt
function parse_git_branch {
 git branch --no-color 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/(\1)/'
}
PS1='\h:\W$(parse_git_branch) \u\$ '

So why didn't we end up on a branch after our pull? When we pulled from Gerrit, we simply copied the information necessary to construct the change set. Any information about branches, etc. didn't get pulled from Gerrit. When get performs a fetch, the commit fetched is pointed to by a special FETCH_HEAD tag. In our case, we grabbed the changes and switched to them. Since there is no branch available at this commit, our prompt reports that we are not on a branch (and are in the "detached head" state). This is confusing, but reading a good git book a few times helps. For now, just trust me that we are in good shape.

Making the fetch better

If we look at the git log we see:

git log
commit 5e76253f0ae70dec8e0b849bbb25799a3cd9c530
Author: Hans Johnson <hans-johnson@uiowa.edu>
Date:   Fri Sep 17 19:31:37 2010 -0500

    Removed unecessary commented out debugging code.

This is helpful, but we don't have the Gerrit Change-Id, so it's hard to push changes back into Gerrit. It is possible to use hooks written by Kitware to add the ChangeId lines to the log automatically. Perhaps someone from Kitware can help out here...

Build, test, review locally

You know what to do here...

Optionally, modify the commit and push changes back into Gerrit for review

Hmmm, I don't actually know how to do this... Sorry... Hopefully Brad King or Brad Lowekamp can fill this in.

Score the change with comments

Back on the change page, we click the "Review" button to enter our review.

Typically, a change requires a score of +2 to be incorporated into the official repo. Certain reviewers are granted the +2 ability, while normal reviewers can give a score of +1. In this case, the changes were straightforward and so I scored a +2.