|
|
Line 1: |
Line 1: |
| __NOTOC__ | | __NOTOC__ |
− | <<[[TableOfContents]]()>>
| + | = Gerrit Workflow Quick Reference = |
| | | |
− | = Quick Reference =
| + | For a more complete description of the setup, see [[GerritJenkinsGitHub]]. |
| | | |
| == Project Setup == | | == Project Setup == |
Line 185: |
Line 185: |
| | | |
| | | |
− | = Gerrit, Jenkins, and [[GitHub]] = | + | == More details ? == |
| | | |
− | [https://github.com/ GitHub] is a resource for managing Git
| + | See [[GerritJenkinsGitHub]]. |
− | 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]].
| |
− | | |
− | == Using Gerrit ==
| |
− | | |
− | The next sections describe how Gerrit fits into the developer
| |
− | workflow.
| |
− | | |
− | === Gerrit Accounts ===
| |
− | | |
− | 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.
| |
− | | |
− | === 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].
| |
− | | |
− | ==== 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.
| |
− | | |
− | The rfc.sh script (or "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].
| |
− | | |
− | ==== 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 rfc.sh, 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):
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | git push gerrit HEAD:refs/for/$BRANCH[/$TOPIC]
| |
− | </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.
| |
− | | |
− | ==== 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:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | Host review
| |
− | Hostname review.openstack.org
| |
− | Port 29418
| |
− | User USERNAME
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | Which may shorten some SSH commands; the following are equivalent:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | ssh -p 29418 review.openstack.org gerrit ls-projects
| |
− | ssh review gerrit ls-projects
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | == 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). A vote of +2 is allowed from core reviewers, but should only be used after another core member has voted +1 and there are no outstanding -1 votes. If you're coming from Launchpad, a +2 vote is equivalent to setting a merge prop status to "Approved". [[OpenStack]] projects have a policy of requiring two core reviewers to approve a patch.
| |
− | | |
− | Once a review receives one +2 vote, Jenkins will run the proposed change and verify the merge. If Jenkins successfully tests the change, and there are no -2 code review votes, the change will be automatically merged into the repository.
| |
− | | |
− | === 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.
| |
− | | |
− | === Gerrit Errors ===
| |
− | | |
− | ==== missing Change-Id in commit message ====
| |
− | | |
− | If you see an error like this:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | ! [remote rejected] HEAD -> refs/for/master (missing Change-Id in commit message)
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | Make sure that you have the [[GerritWorkflow#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:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | The text of your commit message is here.
| |
− |
| |
− | Change-Id: I5f55e68d1bdb42a0fa6f0b1a5432786d0395da51
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | ==== squash commits first ====
| |
− | If you see this message:
| |
− | | |
− | <pre><nowiki>
| |
− | ! [remote rejected] HEAD -> refs/for/master (squash commits first)
| |
− | </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:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | git rebase -i HEAD~2
| |
− | </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:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | pick xxxxxxx 2nd commit back
| |
− | squash yyyyyyy head
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | 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
| |
− | [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.
| |
− | | |
− | = 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:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | git checkout master
| |
− | git pull
| |
− | git checkout milestone-proposed
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | === Authoring Changes for milestone-proposed ===
| |
− | | |
− | Create topic branches as normal, but branch them from
| |
− | milestone-proposed rather than master.
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | git checkout milestone-proposed
| |
− | git pull
| |
− | git checkout -b MY-TOPIC-BRANCH
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | Changes for milestone-proposed should be submitted with:
| |
− | | |
− | <pre><nowiki>
| |
− | git push gerrit HEAD:refs/for/milestone-proposed
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | === 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.
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | 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
| |
− | </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.
| |
− | | |
− | === 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.
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | 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
| |
− | </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.
| |
− | | |
− | === 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:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | git checkout milestone-proposed
| |
− | git pull
| |
− | git tag RELEASE-TAG-NAME
| |
− | git push --tags gerrit
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | === 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 [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]]).
| |
− | | |
− | A description of many of the elements of the [http://sandofsky.com/blog/git-workflow.html git workflow]
| |
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):
First, set these variables to the name of the project and your own
username on Launchpad:
For more information about how to use gerrit, please continue reading.
Once your local repository is set up as above, you must use the
following workflow.
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 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 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: