Difference between revisions of "Obsolete:GerritJenkinsGit"
(make it explicit that reviews.openstack.org is Gerrit.) |
|||
Line 1: | Line 1: | ||
__NOTOC__ | __NOTOC__ | ||
= Gerrit, Jenkins, and [[GitHub]] = | = Gerrit, Jenkins, and [[GitHub]] = | ||
+ | For a quick reference, please see [[GerritWorkflow]] instead. <<[[TableOfContents]]()>> | ||
− | + | [https://github.com/ GitHub] is a resource for managing Git code repositories and interacting with other developers. [http://jenkins-ci.org/ 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. [http://code.google.com/p/gerrit/ 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]]. | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | 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 == | == Using Gerrit == | ||
− | + | The next sections describe how Gerrit fits into the developer workflow. | |
− | The next sections describe how Gerrit fits into the developer | ||
− | workflow. | ||
=== Gerrit Accounts === | === Gerrit Accounts === | ||
+ | Gerrit lives athttps://review.openstack.org/. 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. If your group membership is not correct, please email openstack-ci-admins@lists.launchpad.net . | |
− | |||
− | |||
− | |||
− | 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. If your group membership is not correct, please email | ||
− | openstack-ci-admins@lists.launchpad.net. | ||
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 60: | Line 28: | ||
=== Setting up Git for Use with Gerrit === | === Setting up Git for Use with Gerrit === | ||
− | + | For a more comprehensive look at using Gerrit, see [https://review.openstack.org/Documentation/user-upload.html the Gerrit manual]. | |
− | For a more comprehensive look at using Gerrit, see | ||
− | [https://review.openstack.org/Documentation/user-upload.html the Gerrit manual]. | ||
==== Change-Id Hook ==== | ==== Change-Id Hook ==== | ||
+ | Gerrit uses a '''Change-Id''' footer in commits so that it can link Git commits to changes stored in its database. When you upload a revised change (to correct a problem or respond to code review comments), Gerrit will use the Change-Id footer to attach the commit as a new patchset on the existing gerrit change. This works best if the Change-Id is already in the original commit message, before it is even sent to Gerrit. | ||
− | + | "git review" installs a commit hook into your repository that automatically adds Change-Id lines to your commits.. | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | "git review" installs a commit hook into your | ||
− | repository that automatically adds Change-Id lines to your commits.. | ||
The Gerrit manual goes into more detail about [https://review.openstack.org/Documentation/user-changeid.html change IDs]. | The Gerrit manual goes into more detail about [https://review.openstack.org/Documentation/user-changeid.html change IDs]. | ||
Line 85: | Line 43: | ||
sudo pip install git-review | sudo pip install git-review | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
==== Pushing Changes from Git ==== | ==== Pushing Changes from Git ==== | ||
+ | Simply running '''git review''' should be sufficient to push your changes to Gerrit, assuming your repository is set up as described above, you don't need to read the rest of this section unless you want to use an alternate workflow. | ||
− | + | If you want to push your changes without using git-review, you can push changes to gerrit like you would any other git repository, using the following syntax (assuming "gerrit" is configured as a remote repository): | |
− | |||
− | |||
− | |||
− | |||
− | If you want to push your changes without using git-review, you can push | ||
− | changes to gerrit like you would any other git repository, using the | ||
− | following syntax (assuming "gerrit" is configured as a remote | ||
− | repository): | ||
Line 104: | Line 54: | ||
</nowiki></pre> | </nowiki></pre> | ||
− | + | Where $BRANCH is the name of the Gerrit branch to push to (usually "master"), and you may optionally specify a Gerrit topic by appending it after a slash character. | |
− | Where $BRANCH is the name of the Gerrit branch to push to (usually | ||
− | "master"), and you may optionally specify a Gerrit topic by appending | ||
− | it after a slash character. | ||
==== Git SSH Commands ==== | ==== 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: | |
− | 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: | ||
Line 122: | Line 66: | ||
User USERNAME | User USERNAME | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
Which may shorten some SSH commands; the following are equivalent: | Which may shorten some SSH commands; the following are equivalent: | ||
Line 131: | Line 74: | ||
ssh review gerrit ls-projects | ssh review gerrit ls-projects | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
== Reviewing a Change == | == Reviewing a Change == | ||
+ | Log in to https://review.openstack.org/ to see proposed changes, and review them. | ||
− | + | To provide a review for a proposed change in the Gerrit UI, click on the Review button (it will be next to the buttons that will provide unified or side-by-side diffs in the browser). In the code review, you can add a message, as well as a vote (+1,0,-1). | |
− | |||
− | |||
− | To provide a review for a proposed change in the Gerrit UI, click on the Review | ||
− | button (it will be next to the buttons that will provide unified or side-by-side | ||
− | diffs in the browser). In the code review, you can add a message, as well as a | ||
− | vote (+1,0,-1). | ||
Any Openstack developer may propose or comment on a change (including voting +1/0/-1 on it). Openstack projects have a policy requiring two positive reviews from core reviewers. A vote of +2 is allowed from core reviewers, and should be used to indicate that they are a core reviewer and are leaving a vote that should be counted as such. | Any Openstack developer may propose or comment on a change (including voting +1/0/-1 on it). Openstack projects have a policy requiring two positive reviews from core reviewers. A vote of +2 is allowed from core reviewers, and should be used to indicate that they are a core reviewer and are leaving a vote that should be counted as such. | ||
Line 148: | Line 85: | ||
=== Gerrit Best Practices === | === Gerrit Best Practices === | ||
+ | If you are working on unrelated changes, you should use a [http://progit.org/book/ch3-4.html topic branch] so that there isn't a dependency between the changes. | ||
− | + | When you start working on a new change, make sure you have the current repository head from github. | |
− | |||
− | |||
− | + | For more information about uploading changes to gerrit, see the [https://review.openstack.org/Documentation/user-upload.html Uploading Changes] section of the Gerrit manual. | |
− | |||
− | |||
− | For more information about uploading changes to gerrit, see the | ||
− | [https://review.openstack.org/Documentation/user-upload.html Uploading Changes] section of the Gerrit manual. | ||
=== Gerrit Errors === | === Gerrit Errors === | ||
− | |||
==== missing Change-Id in commit message ==== | ==== missing Change-Id in commit message ==== | ||
− | |||
If you see an error like this: | If you see an error like this: | ||
Line 170: | Line 100: | ||
</nowiki></pre> | </nowiki></pre> | ||
+ | Make sure that you have the [[#Change-Id_Hook|Change-Id hook]] installed. If you don't, install it now, and the run '''git commit --amend''' and re-save your commit message. The hook will then add a Change-Id line. | ||
− | + | If you did have the hook installed, there may be a syntax error with the Change-Id line. It must be in the last paragraph of the commit message, and it must be at the beginning of the line. Your commit message should look like this in your editor: | |
− | |||
− | |||
− | If you did have the hook installed, there may be a syntax error with | ||
− | the Change-Id line. It must be in the last paragraph of the commit | ||
− | message, and it must be at the beginning of the line. Your commit | ||
− | message should look like this in your editor: | ||
<pre><nowiki> | <pre><nowiki> | ||
The text of your commit message is here. | The text of your commit message is here. | ||
− | + | ||
Change-Id: I5f55e68d1bdb42a0fa6f0b1a5432786d0395da51 | Change-Id: I5f55e68d1bdb42a0fa6f0b1a5432786d0395da51 | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
==== squash commits first ==== | ==== squash commits first ==== | ||
If you see this message: | If you see this message: | ||
+ | |||
<pre><nowiki> | <pre><nowiki> | ||
Line 194: | Line 119: | ||
</nowiki></pre> | </nowiki></pre> | ||
− | + | It means that you are trying to update an existing change in Gerrit, but you created two separate commits. Normally to update a change you should ammend an existing commit (see [[GerritWorkflow#Updating_a_Change|Updating a Change]]). If you have already made a second commit, you will need squash the last two commits in your tree. To do that, run: | |
− | It means that you are trying to update an existing change in Gerrit, | ||
− | but you created two separate commits. Normally to update a change you | ||
− | should ammend an existing commit (see [[GerritWorkflow# | ||
− | squash the last two commits in your tree. To do that, run: | ||
Line 205: | Line 126: | ||
</nowiki></pre> | </nowiki></pre> | ||
− | + | Your editor should appear with two commits listed, one per line. Change the word "pick" on the second line to "squash", so that it looks like: | |
− | Your editor should appear with two commits listed, one per line. | ||
− | Change the word "pick" on the second line to "squash", so that it | ||
− | looks like: | ||
Line 216: | Line 134: | ||
</nowiki></pre> | </nowiki></pre> | ||
− | + | And save. You should then be able to upload your commit with '''git review'''. | |
− | And save. You should then be able to upload your commit with '''git | ||
− | review'''. | ||
=== Gerrit Merge Problems === | === Gerrit Merge Problems === | ||
+ | Gerrit will fast-forward or merge changes as necessary when they are approved. If a conflict would be created by a merge, gerrit will not merge the change and will record an error message in the comments for the change. In these cases, you may need to [http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html rebase] or [http://www.kernel.org/pub/software/scm/git/docs/git-merge.html merge] the change, or if the repository head has changed significantly, you may need to change the patch. | ||
− | + | If you don't already have the patch in your local repository, Gerrit provides commands on the web page for each change indicating how to download that change. You can then use git to correct the problem. | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | + | If you encounter other error messages from Gerrit, the [https://review.openstack.org/Documentation/error-messages.html Error Messages] section of the Gerrit manual may offer some tips. | |
− | |||
− | |||
− | |||
− | If you encounter other error messages from Gerrit, the | ||
− | [https://review.openstack.org/Documentation/error-messages.html Error Messages] | ||
− | section of the Gerrit manual may offer some tips. | ||
= Release Management = | = Release Management = | ||
== Milestones == | == Milestones == | ||
+ | Between the Milestone Branch Point and the release of the corresponding milestone, there needs to be a separate branch in Gerrit for changes destined for the milestone release. Meanwhile, development on the master branch should continue as normal (with the addition that changes proposed for the milestone should also be proposed for master, and some changes for master may need to be applied to milestone-proposed). | ||
− | + | This process creates an ephemeral milestone-proposed branch that is only available in Gerrit during the milestone process. When the milestone is released, a tag is applied to the final commit to record the state of the branch at the time. | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | This process creates an ephemeral milestone-proposed branch that is | ||
− | only available in Gerrit during the milestone process. When the | ||
− | milestone is released, a tag is applied to the final commit to | ||
− | record the state of the branch at the time. | ||
=== Create milestone-proposed Branch === | === Create milestone-proposed Branch === | ||
− | |||
This step should be performed by the [[OpenStack]] Release Manager at the Release Branch Point. | This step should be performed by the [[OpenStack]] Release Manager at the Release Branch Point. | ||
Line 265: | Line 157: | ||
* Enter '''milestone-proposed''' in the '''Branch Name''' field, and '''HEAD''' as the Initial Revision, then press '''Create Branch''' | * Enter '''milestone-proposed''' in the '''Branch Name''' field, and '''HEAD''' as the Initial Revision, then press '''Create Branch''' | ||
− | In your local checkout: | + | In your local checkout: |
Line 273: | Line 165: | ||
git checkout milestone-proposed | git checkout milestone-proposed | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
=== Authoring Changes for milestone-proposed === | === Authoring Changes for milestone-proposed === | ||
− | + | Create topic branches as normal, but branch them from milestone-proposed rather than master. | |
− | Create topic branches as normal, but branch them from | ||
− | milestone-proposed rather than master. | ||
Line 287: | Line 176: | ||
</nowiki></pre> | </nowiki></pre> | ||
+ | Changes for milestone-proposed should be submitted with: | ||
− | |||
<pre><nowiki> | <pre><nowiki> | ||
git push gerrit HEAD:refs/for/milestone-proposed | git push gerrit HEAD:refs/for/milestone-proposed | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
=== Submit Changes in master to milestone-proposed === | === Submit Changes in master to milestone-proposed === | ||
− | + | If a change to master should also be included in milestone-proposed, use this procedure to cherry-pick that change and submit it for review. | |
− | If a change to master should also be included in milestone-proposed, | ||
− | use this procedure to cherry-pick that change and submit it for | ||
− | review. | ||
Line 311: | Line 196: | ||
</nowiki></pre> | </nowiki></pre> | ||
− | + | '''git cherry-pick master''' will pick the most recent commit from master to apply, if you want a different patch, use the SHA1 of the commit instead. | |
− | '''git cherry-pick master''' will pick the most recent commit from | ||
− | master to apply, if you want a different patch, use the SHA1 of the | ||
− | commit instead. | ||
=== Submitting Changes in milestone-proposed to master === | === Submitting Changes in milestone-proposed to master === | ||
− | + | Changes that originate in milestone-proposed should also be submitted to master. Use these commands to make an up-to-date topic branch from master, then cherry-pick changes from milestone-proposed to be applied to master. | |
− | Changes that originate in milestone-proposed should also be submitted | ||
− | to master. Use these commands to make an up-to-date topic branch from | ||
− | master, then cherry-pick changes from milestone-proposed to be applied | ||
− | to master. | ||
Line 333: | Line 211: | ||
</nowiki></pre> | </nowiki></pre> | ||
− | + | '''git cherry-pick milestone-proposed''' will pick the most recent commit from milestone-proposed to apply, if you want a different patch, use the SHA1 of the commit instead. | |
− | '''git cherry-pick milestone-proposed''' will pick the most recent | ||
− | commit from milestone-proposed to apply, if you want a different | ||
− | patch, use the SHA1 of the commit instead. | ||
=== Tagging a Release === | === Tagging a Release === | ||
− | |||
This step should be performed by the [[OpenStack]] Release Manager when the release is made. | This step should be performed by the [[OpenStack]] Release Manager when the release is made. | ||
− | To tag the tip of the milestone-proposed branch with a release tag and | + | To tag the tip of the milestone-proposed branch with a release tag and push that tag to gerrit and github, run the following commands: |
− | push that tag to gerrit and github, run the following commands: | ||
Line 352: | Line 225: | ||
git push --tags gerrit | git push --tags gerrit | ||
</nowiki></pre> | </nowiki></pre> | ||
− | |||
Running `git tag -s` signs the tag using GPG, so it's important to ensure that the person making the release have a valid GPG key. | Running `git tag -s` signs the tag using GPG, so it's important to ensure that the person making the release have a valid GPG key. | ||
=== End of Milestone === | === End of Milestone === | ||
− | |||
This step should be performed by the [[OpenStack]] Release Manager after the release is tagged. | This step should be performed by the [[OpenStack]] Release Manager after the release is tagged. | ||
− | When the milestone process is complete and the released commit is | + | When the milestone process is complete and the released commit is tagged, remove the milestone-proposed branch. The tag will persist, even after the branch is deleted, making it possible to restore the state of the tree. |
− | tagged, remove the milestone-proposed branch. The tag will persist, | ||
− | even after the branch is deleted, making it possible to restore the | ||
− | state of the tree. | ||
* Go to https://review.openstack.org/ and sign in | * Go to https://review.openstack.org/ and sign in | ||
Line 371: | Line 239: | ||
= Resources = | = Resources = | ||
+ | See the [https://review.openstack.org/Documentation/index.html 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 [https://wiki.mahara.org/index.php/Developer_Area/Developer_Tools uses Git, Gerrit, and Jenkins] in a similar manner (though with Gitorious instead of [[GitHub]]). | |
− | |||
− | |||
− | |||
− | |||
− | The Mahara Project also | ||
− | [https://wiki.mahara.org/index.php/Developer_Area/Developer_Tools uses Git, Gerrit, and Jenkins] | ||
− | in a similar manner (though with Gitorious instead of [[GitHub]]). | ||
A description of many of the elements of the [http://sandofsky.com/blog/git-workflow.html git workflow] | A description of many of the elements of the [http://sandofsky.com/blog/git-workflow.html git workflow] |
Revision as of 18:23, 6 March 2012
Gerrit, Jenkins, and GitHub
For a quick reference, please see GerritWorkflow instead. <<TableOfContents()>>
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 describe how Gerrit fits into the developer workflow.
Gerrit Accounts
Gerrit lives athttps://review.openstack.org/. 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. If your group membership is not correct, please email openstack-ci-admins@lists.launchpad.net .
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"
Setting up Git for Use with Gerrit
For a more comprehensive look at using Gerrit, see the Gerrit manual.
Change-Id Hook
Gerrit uses a Change-Id footer in commits so that it can link Git commits to changes stored in its database. When you upload a revised change (to correct a problem or respond to code review comments), Gerrit will use the Change-Id footer to attach the commit as a new patchset on the existing gerrit change. This works best if the Change-Id is already in the original commit message, before it is even sent to Gerrit.
"git review" installs a commit hook into your repository that automatically adds Change-Id lines to your commits..
The Gerrit manual goes into more detail about change IDs.
Install the git-review tool, which is the tool OpenStack uses to simplify submission of reviews to Gerrit.
sudo pip install git-review
Pushing Changes from Git
Simply running git review should be sufficient to push your changes to Gerrit, assuming your repository is set up as described above, you don't need to read the rest of this section unless you want to use an alternate workflow.
If you want to push your changes without using git-review, you can push changes to gerrit like you would any other git repository, using the following syntax (assuming "gerrit" is configured as a remote repository):
git push gerrit HEAD:refs/for/$BRANCH[/$TOPIC]
Where $BRANCH is the name of the Gerrit branch to push to (usually "master"), and you may optionally specify a Gerrit topic by appending it after a slash character.
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.
To provide a review for a proposed change in the Gerrit UI, click on the Review button (it will be next to the buttons that will provide unified or side-by-side diffs in the browser). In the code review, you can add a message, as well as a vote (+1,0,-1).
Any Openstack developer may propose or comment on a change (including voting +1/0/-1 on it). Openstack projects have a policy requiring two positive reviews from core reviewers. A vote of +2 is allowed from core reviewers, and should be used to indicate that they are a core reviewer and are leaving a vote that should be counted as such.
When a review has two +2 reviews and one of the core team believes it is ready to be merged, he or she should leave a +1 vote in the "Approved" category. You may do so by clicking the "Review" button again, with or without changing your code review vote and optionally leaving a comment. When a +1 Approved review is received, Jenkins will run tests on the change, and if they pass, it will be merged.
Gerrit Best Practices
If you are working on unrelated changes, you should use a topic branch so that there isn't a dependency between the changes.
When you start working on a new change, make sure you have the current repository head from github.
For more information about uploading changes to gerrit, see the Uploading Changes section of the Gerrit manual.
Gerrit Errors
missing Change-Id in commit message
If you see an error like this:
! [remote rejected] HEAD -> refs/for/master (missing Change-Id in commit message)
Make sure that you have the Change-Id hook installed. If you don't, install it now, and the run git commit --amend and re-save your commit message. The hook will then add a Change-Id line.
If you did have the hook installed, there may be a syntax error with the Change-Id line. It must be in the last paragraph of the commit message, and it must be at the beginning of the line. Your commit message should look like this in your editor:
The text of your commit message is here. Change-Id: I5f55e68d1bdb42a0fa6f0b1a5432786d0395da51
squash commits first
If you see this message:
! [remote rejected] HEAD -> refs/for/master (squash commits first)
It means that you are trying to update an existing change in Gerrit, but you created two separate commits. Normally to update a change you should ammend an existing commit (see Updating a Change). If you have already made a second commit, you will need squash the last two commits in your tree. To do that, run:
git rebase -i HEAD~2
Your editor should appear with two commits listed, one per line. Change the word "pick" on the second line to "squash", so that it looks like:
pick xxxxxxx 2nd commit back squash yyyyyyy head
And save. You should then be able to upload your commit with git review.
Gerrit Merge Problems
Gerrit will fast-forward or merge changes as necessary when they are approved. If a conflict would be created by a merge, gerrit will not merge the change and will record an error message in the comments for the change. In these cases, you may need to rebase or merge the change, or if the repository head has changed significantly, you may need to change the patch.
If you don't already have the patch in your local repository, Gerrit provides commands on the web page for each change indicating how to download that change. You can then use git to correct the problem.
If you encounter other error messages from Gerrit, the Error Messages section of the Gerrit manual may offer some tips.
Release Management
Milestones
Between the Milestone Branch Point and the release of the corresponding milestone, there needs to be a separate branch in Gerrit for changes destined for the milestone release. Meanwhile, development on the master branch should continue as normal (with the addition that changes proposed for the milestone should also be proposed for master, and some changes for master may need to be applied to milestone-proposed).
This process creates an ephemeral milestone-proposed branch that is only available in Gerrit during the milestone process. When the milestone is released, a tag is applied to the final commit to record the state of the branch at the time.
Create milestone-proposed Branch
This step should be performed by the OpenStack Release Manager at the Release Branch Point.
- Go to https://review.openstack.org/ and sign in
- Select Admin, Projects, then the project
- Select Branches
- Enter milestone-proposed in the Branch Name field, and HEAD as the Initial Revision, then press Create Branch
In your local checkout:
git checkout master git pull git checkout milestone-proposed
Authoring Changes for milestone-proposed
Create topic branches as normal, but branch them from milestone-proposed rather than master.
git checkout milestone-proposed git pull git checkout -b MY-TOPIC-BRANCH
Changes for milestone-proposed should be submitted with:
git push gerrit HEAD:refs/for/milestone-proposed
Submit Changes in master to milestone-proposed
If a change to master should also be included in milestone-proposed, use this procedure to cherry-pick that change and submit it for review.
git checkout milestone-proposed git pull git checkout -b master-to-mp git cherry-pick <SHA1 or "master"> git push gerrit HEAD:refs/for/milestone-proposed git branch -D master-to-mp
git cherry-pick master will pick the most recent commit from master to apply, if you want a different patch, use the SHA1 of the commit instead.
Submitting Changes in milestone-proposed to master
Changes that originate in milestone-proposed should also be submitted to master. Use these commands to make an up-to-date topic branch from master, then cherry-pick changes from milestone-proposed to be applied to master.
git checkout master git pull git checkout -b mp-to-master git cherry-pick <SHA1 or milestone-proposed> git review git branch -D mp-to-master
git cherry-pick milestone-proposed will pick the most recent commit from milestone-proposed to apply, if you want a different patch, use the SHA1 of the commit instead.
Tagging a Release
This step should be performed by the OpenStack Release Manager when the release is made.
To tag the tip of the milestone-proposed branch with a release tag and push that tag to gerrit and github, run the following commands:
git checkout milestone-proposed git pull git tag -s RELEASE-TAG-NAME git push --tags gerrit
Running `git tag -s` signs the tag using GPG, so it's important to ensure that the person making the release have a valid GPG key.
End of Milestone
This step should be performed by the OpenStack Release Manager after the release is tagged.
When the milestone process is complete and the released commit is tagged, remove the milestone-proposed branch. The tag will persist, even after the branch is deleted, making it possible to restore the state of the tree.
- Go to https://review.openstack.org/ and sign in
- Select Admin, Projects, then the project
- Select Branches
- Select the checkbox next to milestone-proposed and hit Delete
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, Gerrit, and Jenkins in a similar manner (though with Gitorious instead of GitHub).
A description of many of the elements of the git workflow