|
|
(68 intermediate revisions by 29 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.
| |
− | | |
− | "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].
| |
− | | |
− | Install the git-review tool, which is the tool [[OpenStack]] uses to simplify submission of reviews to Gerrit.
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | sudo pip install git-review
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | ==== 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 [[GerritJenkinsGithub#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 -s RELEASE-TAG-NAME
| |
− | git push --tags gerrit
| |
− | </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.
| |
− | | |
− | === 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]
| |