|
|
| (72 intermediate revisions by 32 users not shown) |
| Line 1: |
Line 1: |
| − | __NOTOC__
| + | Please see the new Developer's Guide here: http://docs.openstack.org/infra/manual/developers.html |
| − | = 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]].
| |
| − | | |
| − | == 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]
| |
