Jump to: navigation, search

Gerrit Workflow

Revision as of 00:10, 25 February 2015 by John Villalovos (talk | contribs) (Add dependency: Explain how to use Depends-On for Inter-Project Dependencies)

Gerrit Workflow Quick Reference

Use this section as a quick reference for commands that you need to run to begin work in a new repository. Read this entire section before you complete the steps in the workflow for the first time. Then, review this section when you start work on a new OpenStack project. For a more complete description of the setup, see GerritJenkinsGit.

Code review static.png

Account Setup

You'll need a Launchpad account, since this is how the Web interface for the Gerrit Code Review system will identify you. This is also useful for automatically crediting bug fixes to you when you address them with your code commits.

If you haven't already, join The OpenStack Foundation (it's free and required for all code contributors). Among other privileges, this also allows you to vote in elections and run for elected positions within The OpenStack Project. When signing up for Foundation Membership, make sure to give the same E-mail address you'll use for code contributions, since this will need to match your preferred E-mail address in Gerrit.

Visit https://review.openstack.org/ and click the Sign In link at the top-right corner of the page. Log in with your Launchpad ID.

Because Gerrit uses Launchpad OpenID single sign-on, you won't need a separate password for Gerrit, and once you log in to one of Launchpad, Gerrit, or Jenkins, you won't have to enter your password for the others.

Unless you are an U.S. Government Employee (see below), agree to the Individual Contributor License Agreement and provide contact information. Your full name and E-mail address will be public (since they also appear in project commit logs) and the latter needs to match the user.email in your Git configuration. The other contact information (postal address, phone numbers) will be kept confidential and is only used as a fallback record in the unlikely event The OpenStack Foundation needs to reach you directly over code contribution related matters. This contact information can also be easily updated later if desired, but make sure the primary E-mail address always matches the one you set for your OpenStack Foundation Membership--otherwise Gerrit will give you an error message and refuse to accept your contact information.

Employees of the the U.S. Government do not sign the Individual CLA. Instead, someone with authority to sign on behalf of your agency should sign the U.S. Government Contributor License Agreement. Please contact the OpenStack Foundation to initiate this process.

If you are contributing on behalf of a company or organization, you still need to sign the ICLA above but someone at your company or organization also needs to sign the Corporate Contributor License Agreement providing a list of people authorized to commit code to OpenStack. Check How to update the CCLA to provide changes to such list. A list of current companies and organizations with an existing Corporate CLA is available for your review.

You'll also want to upload an SSH key while you're at it, so that you'll be able to commit changes for review later.

Ensure that you have run these steps to let git know about your email address:

git config --global user.name "Firstname Lastname"
git config --global user.email "your_email@youremail.com"

To check your git configuration:

git config --list

Git Review Installation

We recommend using the "git-review" tool which is a git subcommand that handles all the details of working with Gerrit, the code review system used in OpenStack development. Before you start work, make sure you have git-review installed on your system.

On Ubuntu, MacOSx, or most other Unix-like systems, it is as simple as:

pip install git-review

On Ubuntu Precise (12.04) and later, git-review is included in the distribution, so install it as any other package:

apt-get install git-review

On Fedora 16 and later, git-review is included into the distribution, so install it as any other package:

yum install git-review

On Fedora 15 and earlier you have to install pip (its package name is `python-pip`), then install git-review using pip in a conventional way.

On Red Hat Enterprise Linux, you must first enable the EPEL repository, then install it as any other package:

yum install git-review

On openSUSE 12.2 and later, git-review is included in the distribution under the name python-git-review, so install it as any other package:

zypper in python-git-review

All of git-review's interactions with gerrit are sequences of normal git commands. If you want to know more about what it's doing, just add -v to the options and it will print out all of the commands it's running.

SSH Setup

If you suffer from an incompetent middlebox in the network between your machine and review.openstack.org then git review and git fetch will mysteriously fail with complaints about "Connection reset by peer". To work around this, create/edit your .ssh/config to reduce the size of your client's Key Exchange Init message; one simple way to do it is to configure the set of MAC algorithms to just one, hmac-md5. When doing a git fetch use an SSH URL rather than an HTTPS one, because your ~/.ssh/config will be consulted in the SSH case but not the HTTPS case.

Project Setup

For Unit Tests Only or With Indirect Integration Testing

This method is suitable for repos on your laptop and supports running unit tests. It also supports both unit testing and indirect integration testing.

Clone a project in the usual way, for example:

git clone git://git.openstack.org/openstack/nova.git

You may want to ask git-review to configure your project to know about Gerrit at this point. If you don't, it will do so the first time you submit a change for review, but you probably want to do this ahead of time so the Gerrit Change-Id commit hook gets installed. To do so (again, using Nova as an example):

cd nova
git review -s

Git-review checks that you can log in to gerrit with your ssh key. It assumes that your gerrit/launchpad user name is the same as the current running user. If that doesn't work, it asks for your gerrit/launchpad user name. You can avoid that question by configuring your Gerrit username, as follows.

git config --global gitreview.username yourgerritusername

If you don't remember your Gerrit user name go to the settings page on gerrit to check it out (it's not your email address).

Note that you can verify the SSH host keys for review.openstack.org here: https://review.openstack.org/#/settings/ssh-keys

If you get the error "We don't know where your gerrit is.", you will need to add a new git remote. The url should be in the error message. Copy that and create the new remote.

git remote add gerrit ssh://<username>@review.openstack.org:29418/openstack/nova.git

In the project directory, you have a `.git` hidden directory and a `.gitreview` hidden file. You can see them with:

ls -la

For System Tests

This method is suitable for running system-level and integration tests with some or all of OpenStack services.

Use DevStack to fetch, configure, and run the set of projects you want in your system. DevStack takes control of the system where it runs and we highly suggest to use it only in disposable virtual machines. It will check out each project repo to the destination defined in your local.conf config file (the default is /opt/stack). You can do the git review setup as above to work in DevStack's repos, but note that DevStack is rather territorial about the repos it checks out and uncommitted changes can be lost when running stack.sh. This is not the recommended way to do more than minor work on projects.

Also note that by default DevStack does not assure installation of the prerequisites for running unit tests. To do that set INSTALL_TESTONLY_PACKAGES=True in local.conf.

Normal Workflow

Once your local repository is set up as above, you must use the following workflow.

Make sure you have the latest upstream changes:

git remote update
git checkout master
git pull --ff-only origin master

Create a topic branch to hold your work and switch to it. If you are working on a blueprint, name your topic branch bp/BLUEPRINT where BLUEPRINT is the name of a blueprint in launchpad (for example, "bp/authentication"). The general convention when working on bugs is to name the branch bug/BUG-NUMBER (for example, "bug/1234567"). Otherwise, give it a meaningful name because it will show up as the topic for your change in Gerrit.

git checkout -b TOPIC-BRANCH

To generate documentation artifacts, navigate to the directory where the pom.xml file is located for the project and run the following command:

mvn clean generate-sources

For complete information about generating documentation artifacts, see "Build Output Locally" on the https://wiki.openstack.org/wiki/Documentation/HowTo page.

Running Unit Tests

See Unit Tests in the Testing page.

Running System Tests

See IntegrationTests on the Testing page.

Committing Changes

Prior to checking in make sure that you run the unit tests.

Git commit messages should start with a short 50 character or less summary in a single paragraph. The following paragraph(s) should explain the change in more detail.

If your changes addresses a blueprint or a bug, be sure to mention them in the commit message using the following syntax:

Implements: blueprint BLUEPRINT
Closes-Bug: ####### (Partial-Bug or Related-Bug are options)

For example:

Adds keystone support

...Long multiline description of the change...

Implements: blueprint authentication
Closes-Bug: 1234567
Change-Id: I4946a16d27f712ae2adf8441ce78e6c0bb0bb657

Note that in most cases the Change-Id line should be automatically added by a Gerrit commit hook that you will want to install. See Project Setup for details on configuring your project for Gerrit. If you already made the commit and the Change-Id was not added, do the Gerrit setup step and run:

git commit --amend

The commit hook will automatically add the Change-Id when you finish amending the commit message, even if you don't actually make any changes.

Make your changes, commit them, and submit them for review:

git commit -a
git review

Caution: Do not check in changes on your master branch. Doing so will cause merge commits when you pull new upstream changes, and merge commits will not be accepted by Gerrit.


Once the code is committed, it appears at https://review.openstack.org. Please refer http://wiki.openstack.org/GerritJenkinsGit for more information. If the link corresponding to your code is clicked, it shows the status and other information. Automatic testing occurs and the results are displayed. Reviewers comment in the comment box or in the code itself.

If someone leaves an in-line comment, you can see it from expanded "Patch Set." "Comments" column shows how many comments are in each file. If you click a file name that has comments, the new page shows a diff page with the reviewer's name and comments. Click "Reply" and write your response. It is saved as a draft if you click "Save." Now, go back to the page that shows a list of patch sets and click "Review," and then, click "Publish comments."

If your code is not ready for review, click "Work in Progress" to indicate that a reviewer does not need to review it for now. Note that the button is invisible until you login the site.

More on what happens next is described on GerritJenkinsGit#Reviewing_a_Change.

Work in Progress

A change can be marked Work in Progress if, for example, it is not ready for merging, or even general code review, but you would still like to get early comments. Marking a change work in progress is simple, leave a comment on your patch setting "Workflow" to -1. Changes in this state are public and can be viewed by everyone. Authenticated users can leave comments as they would in normal code review, but changes in this state cannot be submitted for merging. This allows you to solicit early feedback without worry that incomplete changes will be accidentally merged.

git commit -a
git review
# Go to change in Gerrit web UI and leave a comment with Workflow set to -1.

Caution: The Draft feature in Gerrit may be tempting, but it is not friendly to the CI systems and should not be used. Use the Work in Progress feature instead.

Long-lived Topic Branches

If you are working on a larger project, you may be working on your topic branch for a while. In that case, you may want to check in your changes frequently during development and you must rebase your change to the current state of the master repository before submitting it for code review. In these situations you should prepare your change carefully before submitting it.

If the master repository has changed since you started, you should rebase your changes to the current state. And if you have made many small commits, you should squash them so that they do not show up in the public repository. Remember: each commit becomes a change in Gerrit, and must be approved separately. If you are making one "change" to the project, squash your many "checkpoint" commits into one commit for public consumption. Here's how:

git checkout master
git pull origin master
git checkout TOPIC-BRANCH
git rebase -i master

Use the editor to squash any commits that should not appear in the public history. If you want one change to be submitted to Gerrit, you should only have one "pick" line at the end of this process. After completing this, you can prepare your public commit message(s) in your editor. You start with the commit message from the commit that you picked, and it should have a Change-Id line in the message. Be sure to leave that Change-Id line in place when editing.

Once the commit history in your branch looks correct, run git review to submit your changes to Gerrit.

Updating a Change

If the code review process suggests additional changes, make and amend the changes to the the existing commit. Leave the existing Change-Id: footer in the commit message as-is. Gerrit knows that this is an updated patch for an existing change:

git commit -a --amend
git review

Add dependency

When you want to start new work that is based on the commit under the review, you can add the commit as a dependency.

#fetch change under review and check out branch based on that change.
git checkout -b $DEV_TOPIC_BRANCH
# Edit files, add files to git
git commit 
git review
  • NOTE: git review rebases the existing change (the dependency) and the new commit if there is a conflict against the branch they are being proposed to. Typically this is desired behavior as merging cannot happen until these conflicts are resolved. If you don't want to deal with new patchsets in the existing change immediately you can pass the -R option to git review in the last step above to prevent rebasing. This requires future rebasing to resolve conflicts.
  • NOTE: $PARENT_CHANGE_NUMBER is NOT the Change-Id: value! It is the last section of the gerrit URL. It should be a 5 or 6 digit number.

If the commit your work depends on is updated, and you need to get the latest patch from the depended commit, you can do the following.

# fetch and checkout the parent change
# Note the branch created by git review. Should be review/$USER/$PARENT_CHANGE_ID or similar.
# Checkout existing development topic branch for the child commit.
git checkout $DEV_TOPIC_BRANCH
# Rebase onto updated parent branch to create a dependency on the latest version of that change.
git rebase -i review/$USER/$PARENT_CHANGE #This is the branch created by git review that was noted earlier.
# Do the revisions
git commit -a --amend
# submit for review
git review

The note for the previous example applies here as well. Typically you want the rebase behavior in git review. If you would rather postpone resolving merge conflicts you can use git review -R as the last step above.

Inter-Project Dependency

If you want your patch set to depend on a patch set in a different project you need to add 'Depends-On: $CHANGE_ID' line where $CHANGE_ID is replaced with the Change-Id of the patch you depend on. This line should be grouped with the Change-ID line.

For example:

commit 5bc293b93c3a31bcbc0097e4f2b4717f5c79abcd
Author: Joe Sixpack <joe.sixpack@example.com>
Date:   Tue Feb 24 14:18:45 2015 -0800

    A patch
    My patch that patches things
    Change-Id: I321604c47e051c908d3a5e56274eeb535fabcdef
    Depends-On: Ia111343944db7dfc535e9da0a1e41b3f6fabcdef

Maintaining Dependency Chains

Gerrit dependency chains may become very long and may require collaboration from many individuals. Without proper understanding of Gerrit and proper maintenance of these chains, this process can become very frustrating.

Understanding Reviews and Patch Sets


Each review is determined by the Change-Id in the commit message. That's why doing "git commit --amend" is suggested when making changes to a review. Two different Change-Ids means two different reviews.

Patch Sets

A patch set is determined by a change in the commit hash. When a review is initially pushed up it only has one patch set. When a change is done for that review "git commit --amend" is typically used to commit changes, followed by a "git review" to push those changes up. "git commit --amend" will change the most current commit's hash because it is essentially a new commit with the changes from the previous state combined with the new changes added. Since it is a new commit hash, once a "git review" is successfully processed, a new patch set appears in Gerrit.

Since a patch set is determined by a change in the commit hash, many git commands will cause new patch sets. Three common ones that do this are:

  • git commit --amend
  • git rebase
  • git cherry-pick

Common Problems

  • Pushing up a change to your review that is dependent on other reviews inadvertently changes the dependents as well.
    • This is probably because a change you made caused the dependent commits' hashes to change so "git review" tries to push all of these up to Gerrit.

Common Scenarios

Rebase On Dependent

Only needing to rebase your review on a dependent reviews change is very simple and two methods to accomplish this. There are no advantages of one method over the other, except for your view of which is more convenient.

  • Gerrit Rebase Button
    • Click "Rebase" button in the Gerrit UI under your patch set.
  • Local rebasing.
    • This requires copying the "cherry-pick" option provided in the child's patch set details of the Gerrit UI.
    • The reason git review -R is done is because it should be up to the parent to rebase based on its parent. If a conflict occurs it should be their responsibility to fix the conflict and your responsibility to rebase off of that fix.
  1. Checkout and create local branch of the dependent review - git review -d $PARENT_CHANGE_NUMBER
  2. Cherry-pick your review's most recent patch set - copied from Gerrit UI
  3. Push up - git review -R
Rebase On Dependent and Make Changes
  • Gerrit Rebase Button and Changing Locally
    • The problem with this is that it creates two patch sets.
  1. Click "Rebase" button in Gerrit UI
  2. git review -d $PARENT_CHANGE_NUMBER
  3. Make changes
  4. git commit --amend
  5. git review -R
  • Local Rebasing and Changing Locally
    • Requires cherry-pick from child review
    • Creates only one patch set
  1. Checkout and create local branch of the dependent review - git review -d $PARENT_CHANGE_NUMBER
  2. Cherry-pick your review's most recent patch set - copied from Gerrit UI
  3. Make changes - git commit --amend
  4. Push up - git review -R

Make changes to many reviews and push them all up at once

This is actually using the same method that causes the common problems listed above. The use case is if you are the owner of many reviews that create a dependency chain and you need to make changes to each review. The easy way is to just pull down each review and make the changes and then push back up, then rebase the child review, make changes, and push back up. Repeat. Another way that requires less steps is to use the edit mode in git's rebase and then push all the changes up at once. Here are the steps:

  1. Pull down the last review in the chain you need to make a chain in (usually this is just the last review you own in the chain since that one will need to be rebased anyway).
  2. do an interactive rebase back to the first commit you need to make a change in.
  3. in the editor mode, replace "pick" on all the commits you need to make changes to with an "e" (or "edit")
  4. Make changes
  5. Amend commit
  6. continue rebase
  7. repeat until rebase has finished


# pull down last review in the dependency chain
git review -d $LAST_REVIEW_IN_CHAIN
# get the first commit's hash that you want to start making changes on
git log
# start rebase interactively between current HEAD and the first commit's (the ^ is important and literal)
git rebase -i $FIRST_COMMIT^
# In editor mode, replace "pick" with "e" or "edit" for all commits you want to change
# Make changes
# Amend commit
git commit --amend
# Continue to next edited commit
git rebase --continue
# Repeat making changes, git commit --amend, and git rebase --continue until rebase is complete.
# Push all changes up
git review