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 GerritJenkinsGithub.
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.
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 "firstname.lastname@example.org"
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, 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, or on Red Hat Enterprise Linux, you have to install pip (its package name is `python-pip`), then install git-review using pip in a conventional way.
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.
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 will check that you can log into gerrit with your ssh key. It assumes that your gerrit/launchpad username is the same as the current running user. If that doesn't work, it will ask for your gerrit/launchpad username. If you don't remember the username 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:
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 (e.g., "bp/authentication"). The general convention when working on bugs is to name the branch bug/BUG-NUMBER (e.g., "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
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:
blueprint BLUEPRINT bug #######
Adds keystone support ...Long multiline description of the change... Implements: blueprint authentication Fixes: bug #123456 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.
Prior to checking in make sure that you run "tox".
Once the code is committed, it appears at https://review.openstack.org. Please refer http://wiki.openstack.org/GerritJenkinsGithub for more information. If the link corresponding to your code is clicked, it will show the status and other information. Automatic testing will be done and the results will be displayed once they are complete. Reviewers will come and review and leave comments in the comment box or in the code itself.
If there is an in-line comment, you can see it from expanded "Patch Set." "Comments" column will show how many comments are in each file. If you click a file name that has comments, the new page will show a diff page with the reviewer's name and comments. Click "Reply" and write your response. It will be 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 GerritJenkinsGithub#Reviewing_a_Change.
A change can be submitted as a draft if, for example, it's not ready for merging, or even general code review, but you would like to share it selectively to get early comments. If you upload a change as a draft, by default, no one else can see it. You must explicitly add each person you would like to share it with as a reviewer. Reviewers you add can leave comments, but cannot vote at this stage. You can continue to upload new patchsets to the change as it evolves, and once it is ready for general review, you can click the "Publish" button. It will then become a normal change in Gerrit that everyone can see, including the earlier reviews from the draft stage. This is a one way transition; once a draft is published, it can't be made a draft again.
A draft change is uploaded by adding the "-D" option. Simply make changes, commit them, and submit them as a draft:
git commit -a git review -D
Caution: Earlier versions (prior to 1.16) of git-review may also have the "-D" option, but the git ref that Gerrit uses to indicate a change should be a draft was changed; so if using "-D" results in an error, you may need to upgrade to latest.
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 will need to 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 will become a change in Gerrit, and need to 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 to do both of those:
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 will be able to prepare your public commit message(s) in your editor. You will 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
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 config git fetch https://review.openstack.org/openstack/nova refs/changes/16/10816/9 && git checkout FETCH_HEAD git checkout -b SOMEBRANCHNAME git review -R
- NOTE* -R option is very important. If you omit the -R option, the original commit is updated by mistake.
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. First you need to note the parent-id of the change on the depended commit, and checkout a new branch with the parent id as the commit id:
# check out the parent commit of the depended commit. SHA1 is the commit id. git checkout -b aNewBranch SHA1 # cherry pick the depended commit git fetch https://review.openstack.org/openstack/nova refs/changes/80/28880/40 && git cherry-pick FETCH_HEAD # cherry pick your last commit git fetch https://review.openstack.org/openstack/nova refs/changes/28/30028/6 && git cherry-pick FETCH_HEAD # Do the revisions # commit git commit -a --amend # submit for review git review -R
If you only do a rebase with the master branch and then cherry pick the depended commit and your own last commit, even when you do "git review -R", both depended commit and your commit will be updated. This is due to the potential mismatch between the parent-id of the depended commit and the current commit id of the master branch.