Revision as of 18:00, 7 November 2011

Gerrit Workflow Quick Reference

For a more complete description of the setup, see GerritJenkinsGithub.

<<TableOfContents()>>

Project Setup

This section is intended as a quick reference of commands needed to begin work in a new repository. Please read this entire documentation to understand the workflow in use, and then consult this section when you need to start work on a new OpenStack project.

Before setting up your first project, add a global git alias to make reviewing easier (you only have to do this once, not for each project):

cat <<EOF >>~/.gitconfig
[alias]
	review = !sh \`git rev-parse --show-toplevel\`/tools/rfc.sh
EOF

If you are going to contribute code to a project, run the following commands for each project you intend to work with.

To identify the list of available projects, run the following command:

USERNAME=jsmith
ssh -p29418 -o StrictHostKeyChecking=no $USERNAME@review.openstack.org gerrit ls-projects

Note: SSH public key should be updated to https://review.openstack.org/#settings,ssh-keys

As of Oct. 17, 2011, the list of available projects is:

API-Projects
All-Projects
openstack-ci/git-review
openstack/compute-api
openstack/glance
openstack/identity-api
openstack/image-api
openstack/keystone
openstack/netconn-api
openstack/nova
openstack/object-api
openstack/openstack-chef
openstack/openstack-ci
openstack/openstack-ci-puppet
openstack/openstack-integration-tests
openstack/openstack-manuals
openstack/openstack-puppet
openstack/quantum
openstack/swift

Next, set these variables to the name of the project and your own username on Launchpad:

PROJECT=nova
USERNAME=jsmith

Then run the following commands to clone the repository and configure it for use with Gerrit:

# Clone the repository
git clone git://github.com/openstack/$PROJECT.git

# Set up the Gerrit Change-Id hook, and remote repository:
scp -p -P 29418 $USERNAME@review.openstack.org:hooks/commit-msg .git/hooks
cd $PROJECT
git review

The command git review calls the global git alias you set up earlier. It invokes the script "tools/rfc.sh" which we maintain in each OpenStack repository. It makes sure that the Gerrit Change-Id hook is installed, the gerrit remote repository is configured, your changes are based on the tip of the master repository, and submits your changes with an appropriate topic.

For more information about how to use gerrit, please continue reading.

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 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"). Otherwise, give it a meaningful name because it will show up as the topic for your change in Gerrit.

git checkout -b TOPIC-BRANCH

Committing Changes

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 #######

e.g.:

Adds keystone support.

Implements blueprint authentication.  Fixes bug 123456.

(Long description of the change).

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

git commit -a
git review

#!wiki caution
'''Note'''

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 "./run_tests.sh -p"

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 them and ammend the existing commit. Leave the existing Change-Id: footer in the commit message as-is and Gerrit will know that this is an updated patch for an existing change:

git commit -a --amend 
git review

Git Review Workflow

This section describes the new recommendend workflow using the git-review tool, currently in testing. If you aren't testing git-review, please use the section above instead.

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:

pip install git-review

Project Setup

Clone a project in the usual way, for example:

git://github.com/openstack/nova.git

You may want to ask git-review to configure your project to know about Gerrit at this point (though if you don't, it will do so the first time you submit a change for review). 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.

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 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"). Otherwise, give it a meaningful name because it will show up as the topic for your change in Gerrit.

git checkout -b TOPIC-BRANCH

Committing Changes

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 #######

e.g.:

Adds keystone support.

Implements blueprint authentication.  Fixes bug 123456.

(Long description of the change).

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

git commit -a
git review

#!wiki caution
'''Note'''

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 "./run_tests.sh -p"

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 them and ammend the existing commit. Leave the existing Change-Id: footer in the commit message as-is and Gerrit will know that this is an updated patch for an existing change:

git commit -a --amend 
git review

More details ?

See GerritJenkinsGithub.