Difference between revisions of "Gerrit Workflow"
(incorrect info about .gitreview file) |
(.gitreview file) |
||
Line 1: | Line 1: | ||
__NOTOC__ | __NOTOC__ | ||
= Gerrit Workflow Quick Reference = | = Gerrit Workflow Quick Reference = | ||
− | + | 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. | |
− | 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. | ||
For a more complete description of the setup, see [[GerritJenkinsGithub]]. | For a more complete description of the setup, see [[GerritJenkinsGithub]]. | ||
<<[[TableOfContents]]()>> | <<[[TableOfContents]]()>> | ||
+ | |||
== Account Setup == | == Account Setup == | ||
− | Make sure you have a launchpad account, and you have uploaded your ssh | + | Make sure you have a launchpad account, and you have uploaded your ssh public keys to it. |
− | public keys to it. | ||
− | Visit https://review.openstack.org/ and click the '''Sign In''' link | + | 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. |
− | 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 | + | 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. |
− | 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. | ||
− | Gerrit accounts are automatically synchronized with Launchpad, so | + | Gerrit accounts are automatically synchronized with Launchpad, so your Gerrit account should already have the same username, full name, email address, ssh keys, and group membership. |
− | your Gerrit account should already have the same username, full name, | ||
− | email address, ssh keys, and group membership. | ||
− | Some information in Launchpad is not publicly available and so may not | + | Some information in Launchpad is not publicly available and so may not be copied over. The first time you log into Gerrit, you should click the '''Settings''' link at the top of the page, and then make sure that your '''Contact Information''', '''SSH Public Keys''', and '''Groups''' look correct. If not, please register your email address and SSH keys. |
− | be copied over. The first time you log into Gerrit, you should click | ||
− | the '''Settings''' link at the top of the page, and then make sure | ||
− | that your '''Contact Information''', '''SSH Public Keys''', and | ||
− | '''Groups''' look correct. If not, please register your email address | ||
− | and SSH keys. | ||
Ensure that you have run these steps to let git know about your email address: | Ensure that you have run these steps to let git know about your email address: | ||
Line 39: | Line 25: | ||
git config --global user.email "your_email@youremail.com" | git config --global user.email "your_email@youremail.com" | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
To check your git configuration: | To check your git configuration: | ||
Line 47: | Line 32: | ||
git config --list | git config --list | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
== Git Review Installation == | == 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. | |
− | 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: | On Ubuntu, or most other Unix-like systems, it is as simple as: | ||
Line 63: | Line 43: | ||
</nowiki></pre> | </nowiki></pre> | ||
− | + | On Ubuntu Precise (12.04) and later, git-review is included in the distribution, so install it as any other package: | |
− | On Ubuntu Precise (12.04) and later, git-review is included in the distribution, | ||
− | so install it as any other package: | ||
Line 72: | Line 50: | ||
</nowiki></pre> | </nowiki></pre> | ||
− | + | On Fedora 16 and later, git-review is included into the distribution, so install it as any other package: | |
− | On Fedora 16 and later, git-review is included into the distribution, | ||
− | so install it as any other package: | ||
Line 81: | Line 57: | ||
</nowiki></pre> | </nowiki></pre> | ||
− | + | 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 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. | ||
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. | 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. | ||
== Project Setup == | == Project Setup == | ||
− | |||
Clone a project in the usual way, for example: | Clone a project in the usual way, for example: | ||
Line 97: | Line 69: | ||
</nowiki></pre> | </nowiki></pre> | ||
− | + | 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): | |
− | 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): | ||
Line 109: | Line 77: | ||
</nowiki></pre> | </nowiki></pre> | ||
− | + | 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. | |
− | 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 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. | 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. | ||
Line 122: | Line 86: | ||
</nowiki></pre> | </nowiki></pre> | ||
+ | |||
+ | In the project directory, you have a `.git` hidden directory and a `.gitreview` hidden file. You can see them with: | ||
+ | |||
+ | <pre><nowiki> | ||
+ | ls -la | ||
+ | </nowiki></pre> | ||
== Normal Workflow == | == 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: | |
− | |||
− | |||
<pre><nowiki> | <pre><nowiki> | ||
Line 136: | Line 105: | ||
</nowiki></pre> | </nowiki></pre> | ||
− | + | Create a [http://progit.org/book/ch3-4.html 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. | |
− | Create a [http://progit.org/book/ch3-4.html 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. | ||
Line 148: | Line 111: | ||
git checkout -b TOPIC-BRANCH | git checkout -b TOPIC-BRANCH | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
=== Committing Changes === | === 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: | |
− | |||
− | |||
− | |||
− | If your changes addresses a blueprint or a bug, be sure to mention | ||
− | them in the commit message using the following syntax: | ||
Line 164: | Line 122: | ||
bug ####### | bug ####### | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
e.g.: | e.g.: | ||
Line 176: | Line 133: | ||
(Long description of the change). | (Long description of the change). | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
Make your changes, commit them, and submit them for review: | Make your changes, commit them, and submit them for review: | ||
Line 185: | Line 141: | ||
git review | git review | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
Line 197: | Line 152: | ||
Prior to checking in make sure that you run "./run_tests.sh -p" | Prior to checking in make sure that you run "./run_tests.sh -p" | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
=== Drafts === | === Drafts === | ||
− | |||
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 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. | ||
Line 210: | Line 163: | ||
git review -D | git review -D | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
Line 218: | Line 170: | ||
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. | 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. | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
=== Long-lived Topic Branches === | === 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: | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | 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: | ||
Line 245: | Line 184: | ||
</nowiki></pre> | </nowiki></pre> | ||
+ | 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. | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | Once the commit history in your branch looks correct, run '''git | ||
− | review''' to submit your changes to Gerrit. | ||
=== Updating a Change === | === 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: | |
− | 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: | ||
<pre><nowiki> | <pre><nowiki> | ||
− | git commit -a --amend | + | git commit -a --amend |
git review | git review | ||
</nowiki></pre> | </nowiki></pre> |
Revision as of 16:49, 11 May 2012
Gerrit Workflow Quick Reference
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.
For a more complete description of the setup, see GerritJenkinsGithub.
<<TableOfContents()>>
Account Setup
Make sure you have a launchpad account, and you have uploaded your ssh public keys to it.
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.
Gerrit accounts are automatically synchronized with Launchpad, so your Gerrit account should already have the same username, full name, email address, ssh keys, and group membership.
Some information in Launchpad is not publicly available and so may not be copied over. The first time you log into Gerrit, you should click the Settings link at the top of the page, and then make sure that your Contact Information, SSH Public Keys, and Groups look correct. If not, please register your email address and SSH keys.
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, 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.
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.
Project Setup
Clone a project in the usual way, for example:
git clone 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.
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
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"
Drafts
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
#!wiki caution '''Note:''' 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 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