Gerrit Workflow
#!wiki caution '''Note''' This workflow for developers is a work in progress and is not ready for use by OpenStack projects. Please see [[LifeWithBzrAndLaunchpad]] for current project practices.
<<TableOfContents()>>
Gerrit, Jenkins, and GitHub Workflow
GitHub is a resource for managing Git code repositories and interacting with other developers. Jenkins is used to continuously test all of the components of OpenStack to ensure functionality and to verify that each change to the code base works as intended. Gerrit is a code review system originally developed for use by the Android Open Source Project and allows us to build a workflow where every change is peer-reviewed and tested by Jenkins before being merged into the main repository.
After making a change in their local Git repository, developers can easily push that change to Gerrit as a proposed change for the project. Jenkins will automatically run functional tests on the code and provide feedback on the change in Gerrit. Any OpenStack developer can provide feedback (in the form of a comment, or even line-by-line annotations) using Gerrit, and the core developers of the project can indicate whether they approve of the patch as is, or would like to see changes before it is integrated. Once patches are merged by Gerrit, the repository is pushed to the canonical public repository on GitHub.
Using Gerrit
The next sections will describe what steps a developer should take to use Gerrit as part of this workflow.
Register for an Account with Gerrit
Visit https://review.openstack.org/ and click the Register link at the top-right corner of the page. Log in with your Launchpad ID, which looks like:
https://launchpad.net/~USERNAME
Where USERNAME is your Launchpad username. Because Gerrit uses OpenID, you won't need a separate password for Gerrit. As part of the registration process, you will need to upload your SSH public key. You may have already done this when registering with Launchpad, if so you may use the same key. See the Gerrit manual for more information.
When Gerrit asks you to choose a username, choose the same one you use on Launchpad.
#!wiki caution '''Note''' The OpenStack Gerrit site currently uses a self-signed SSL certificate; this will be replaced with a certificate from a recognized CA soon. Additionally, we hope to automatically sync Gerrit accounts, groups, and SSH keys from Launchpad in the near future so developers will be able to skip this step.
Cloning a Git Repository
Clone a copy of the repository for the OpenStack project you want to work on from GitHub using a command similar to the following:
git clone git://github.com/openstack/PROJECT.git
Or if you have a GitHub account, via SSH:
git clone git@github.com:openstack/PROJECT.git
Where PROJECT is the name of the project you want to work on. The
correct path to use can also be found on the project's page on GitHub.
Setting up Git for Use with Gerrit
For a more comprehensive look at using Gerrit, see the Gerrit manual.
Change-Id Hook
Gerrit adds a Change-Id header to commits so that it can link Git commits to changes stored in its database. It will add it automatically if not present, but frequent Gerrit users may want to have the header added locally before being uploaded to Gerrit. In particular, this will make updating patches for existing changes easier. To cause the Change-Id header to be added automatically to each commit message, run this command inside your repository:
scp -p -P 29418 USERNAME@review.openstack.org:hooks/commit-msg .git/hooks/
Where USERNAME is the username you registered with Gerrit.
Git Remote
To make pushing proposed changes to Gerrit easier, you may register Gerrit as a remote repository tracked by Git. Run the following command inside your local Git repository:
git remote add gerrit ssh://USERNAME@review.openstack.org:29418/openstack/PROJECT.git
Where USERNAME is the username you registered with Gerrit and
PROJECT is the name of the current project. Then when you are
ready to push a change to Gerrit for review, you may issue a command
like:
git push gerrit HEAD:refs/for/master
Git SSH Commands
If you find you are frequently executing Gerrit commands via SSH, you may wish to add something like the following to your ~/.ssh/config file:
Host review Hostname review.openstack.org Port 29418 User USERNAME
Which may shorten some SSH commands; the following are equivalent:
ssh -p 29418 review.openstack.org gerrit ls-projects ssh review gerrit ls-projects
Reviewing a Change
Log in to https://review.openstack.org/ to see proposed changes, and review them. Any Openstack developer may propose or comment on a change (including voting on it). Members of the core project team may mark changes as approved (by voting +2), and once a change has at least one +2 vote, no -2 votes, and Jenkins has tested the change and verified it, the change can be submitted by a member of the core developer group to be merged into the repository.
Resources
See the Gerrit documentation, especially the User Guide, for more information on how to use Gerrit. It is also available within Gerrit by clicking on the Documentation link on the top of the page.
The Mahara Project also uses Git, Gerit, and Jenkins in a similar manner (though with Gitorious instead of GitHub).