Using Gerrit

Gerrit is primarily a code inspection tool, but can also be used to track the status of patch as it is build tested, and finally merged to a branch. Developers submit patches to Gerrit using git, and there is a rich browser interface for performing inspections. Inspectors can also pull the change directly to their own repository and inspect the change locally.

To upload changes to Gerrit, you must first register and add an ssh key to your account.  For details on setting up your Gerrit account and sending patches, please see the Gerrit documentation.

Gerrit can host many git repositories, and of course each of those repositories can contain many branches. For instance, these are some of the repositories on Gerrit today:

Managing Changes in Git

Whole books could be written about this topic, and there plenty of online tutorials on the web that explain this in more detail and suggest other methods of managing changes. However, this distilled version is (hopefully) enough to get started.

Typically in git, one creates a new local branch for each change being made. The branch is created based on one of the local, pristine branches follow the main development branches, such as b1_8 or master. A new local branch is usually create using checkout:

$ git checkout -b my-brilliant-idea master

This creates a new branch based on master called my-brilliant-idea, and also makes it the current branch.

Once you've made the change, and you're ready to create an inspection, you commit. Before you commit in git, you need to identify which files you want to commit using the "git add" command. If you haven't added any new files, and you want to commit all the files that you have changed (which is the usual case), then you can use the "-a" option to commit:

$ git commit -av

This will put you into an editor to update your commit comment, and when you save it will commit the change locally. The -v option appends the diff to the edit buffer so you can review what is about to be committed. This is very handy.

It is best to commit relatively frequently to keep your changes limited to a single fix. If you notice other, unrelated, issues that need to be fixed, then it's best to put them in a different commit, and usually on a different branch. The stash command is handy for this:

# While fixing a bug you notice something evil that must be fixed.
# First set your current work aside:
$ git stash

# Next go create a new branch and purge the ugliness you just discovered:
$ git create -b my-eyes-are-bleeding master
$ git commit -av

# Now go back to what you were working on:
$ git checkout my-brilliant-idea
$ git stash pop

Formatting Git Commit Comments

Comments should be wrapped to about 72 columns. This allows for the first line to be used a subject in emails, and also for the entire body to be displayed using tools like "git log" in an 80 column window.

The first line of the comment is the subject or summary of the change, and should include the Lustra Jira ID at the beginning of the line. A Lustre Jira ticket is one that begins with LU and is therefore part of the Lustre project within Jira. If the patch is submitted for the fs/lustre-release repository without a Lustre Jira ID in the first line, then it will automatically receive a -2 review which will prevent the patch from being submitted to a release branch.

Please make sure the Change-Id: line are on the bottom of the comment. This is also both required (as is the Signed-off-by line) by the fs/lustre-release project (at least) in order for the patch to be approved.  If your comments are excluding the Change-Id the patch will be rejected at submission time. The Change-Id field should be added using the commit-msg hook, see below.

Sample Commit message

LU-999 Single line description of the change

A more detailed explanation.  This can be as detailed as you'd like.
Please explain both what problem was solved and a high-level
description of how it was solved.

Signed-off-by: Random J Developer <random@developer.example.org>
Change-Id: Ica9ed1612eab0c4673dee088f8b441d806c64932

Adding the Change-Id field

Gerrit will automatically identify updates to existing patches and update the existing request instead of creating a new one. For this to work properly the changes you create locally need to have a commit id in them. To get this inserted automatically, add the commit-msg hook provided by Gerrit to your repository. This will update the commit message you commit your changes to your repository. Here are two ways to get the hook:

$ scp -p -P 29418 review.whamcloud.com:hooks/commit-msg .git/hooks/

$ curl -o .git/hooks/commit-msg http://review.whamcloud.com/tools/hooks/commit-msg

Alternatively, you can use the commit-msg that's included in the attachments section of this page to get all of an empty Issue: line, a Signed-off-by: line with your git configured name and e-mail address and a Change-Id.

Note that you might have add the required execute permissions to the hook once you have fetched it:

$ chmod 755 .git/hooks/commit-msg

Creating Inspection Requests

An inspection request is created by pushing a change to a special branch on the gerrit repository. For example, to create a request for a change against master on the main lustre repository, you do this your current working branch on your local branch for inspection:

git push ssh://USER@review.whamcloud.com:29418/fs/lustre-release HEAD:refs/for/master

or

git push ssh://USER@review.whamcloud.com:29418/tools/e2fsprogs HEAD:refs/for/master-lustre

For convenience, you can add this to your ~/.ssh/config file:

Host review
  Hostname review.whamcloud.com
  Port 29418
  User change.me
  IdentityFile ~/.ssh/my-key-id_rsa

Creating an inspection request for a change against master (assuming the remote alias has been added to ssh config):

git push ssh://review/fs/lustre-release HEAD:refs/for/master

And add a the Gerrit server as a remote to your git repository:

$ git remote add review ssh://review/fs/lustre-release

Pushing a Git Tag

Switch to the branch you want to create a branch in (normally master or b1_8).

Create the tag with

git tag -a TAG_NAME

then push it upstream with

git push TAG_NAME

Note, this requires certain privileges on the server. If review is a secondary server for your repository, use

git push review TAG_NAME

Updating Inspection Requests

Gerrit makes it easy to update an inspection request with a new patch, and doing this allows inspectors to see differences between the patches so they only need to inspect the changes. Also, the original inline comments are maintained and moved to the new patches. The key to updating inspection requests is the Change-Id field - this is what Gerrit uses to find the original patch to update.

And key thing to point out is you need update a new version of the full change - not just an update to the change. The usual way of doing this is to apply the updates to your tree as usual and create a new commit (this time the commit message doesn't matter as you are about to change it). Then the key step is to merge the two changes using "git rebase -i <parent-branch>". Interactive rebase will display a list of patches in an editor, and you can "squash" the the new patch onto the original. (See the help text in the editor window for more information.) Then it you put in an editor again to manually merge the two commit messages. Make sure you keep the original Change-Id line, and delete the new one, and edit the commit messages so it's combined into a single commit. Once that is done, push your branch again, and the original request will be updated with the new version of the patch.

The easiest way to update the most recent commit (which is often the one you want to update), is to use git commit --amend -a.