|
|
(146 intermediate revisions by 58 users not shown) |
Line 1: |
Line 1: |
− | __NOTOC__
| + | Please see the new Developer's Guide here: https://docs.openstack.org/infra/manual/developers.html |
− | | |
− | <pre><nowiki>#!wiki caution
| |
− | '''Note'''
| |
− | | |
− | This workflow for developers is a work in progress and is not ready
| |
− | for use by OpenStack projects. Please see [[LifeWithBzrAndLaunchpad]]
| |
− | for current project practices.
| |
− | | |
− | </nowiki></pre>
| |
− | | |
− | | |
− | <<[[TableOfContents]]()>>
| |
− | | |
− | = Quick Reference =
| |
− | | |
− | == Project Setup ==
| |
− | | |
− | 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.
| |
− | | |
− | If you are going to contribute code to a project, run the following
| |
− | commands for each project you intend to work with.
| |
− | | |
− | First, set these variables to the name of the project and your own
| |
− | username on Launchpad:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | PROJECT=keystone
| |
− | USERNAME=jsmith
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | Then run the following commands to clone the repository and configure
| |
− | it for use with Gerrit:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | # Clone the repository
| |
− | git clone git://github.com/openstack/$PROJECT.git
| |
− | | |
− | # Install the Change-Id commit message hook:
| |
− | cd $PROJECT
| |
− | scp -p -P 29418 $USERNAME@review.openstack.org:hooks/commit-msg .git/hooks/
| |
− | | |
− | # Add Gerrit as a remote repository:
| |
− | git remote add gerrit ssh://$USERNAME@review.openstack.org:29418/openstack/$PROJECT.git
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | If this is the first project you have set up with Gerrit, you should
| |
− | add a global git alias to make reviewing easier (you only have to do
| |
− | this once, not for each project):
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | cat <<EOF >>~/.gitconfig
| |
− | [alias]
| |
− | review = push gerrit HEAD:refs/for/master
| |
− | EOF
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | For more information about how to use gerrit, please continue reading.
| |
− | | |
− | == Normal Workflow ==
| |
− | | |
− | Once your local repository is set up as above, the following Git
| |
− | workflow is recommended:
| |
− | | |
− | Make sure you have the latest upstream changes:
| |
− | | |
− | <pre><nowiki>
| |
− | git checkout master
| |
− | git pull origin master
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | Create a [http://progit.org/book/ch3-4.html topic branch] to hold your work:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | git branch my-topic-name
| |
− | git checkout my-topic-name
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | Make your changes, commit them, and submit them for review:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | git commit -a
| |
− | git review
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | === 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:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | git commit -a --amend
| |
− | git review
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | = Gerrit, Jenkins, and [[GitHub]] Workflow =
| |
− | | |
− | [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 will describe what steps a developer should take to
| |
− | use Gerrit as part of this 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.
| |
− | | |
− | | |
− | <pre><nowiki>#!wiki caution
| |
− | '''Note'''
| |
− | | |
− | The OpenStack Gerrit site currently uses a self-signed SSL
| |
− | certificate; this will be replaced with a certificate from a
| |
− | recognized CA soon.
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | 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.
| |
− | | |
− | | |
− | <pre><nowiki>#!wiki caution
| |
− | '''Note'''
| |
− | | |
− | For each project you contribute to, you will want to make Gerrit
| |
− | notify you of changes to the project's master repo. To do so, you will
| |
− | want to go to https://review.openstack.org/#settings,projects and
| |
− | enter the names of projects to watch.
| |
− | | |
− | </nowiki></pre>
| |
− | | |
− | | |
− | === Cloning a Git Repository ===
| |
− | | |
− | Clone a copy of the repository for the [[OpenStack]] project you want to
| |
− | work on from [[GitHub]] using a command similar to the following:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | git clone git://github.com/openstack/$PROJECT.git
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | Or if you have a [[GitHub]] account, via SSH:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | git clone git@github.com:openstack/$PROJECT.git
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | Where ''$PROJECT'' is the name of the project you want to work on. The
| |
− | correct path to use can also be found on the project's page on [[GitHub]].
| |
− | | |
− | === 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.
| |
− | | |
− | Use the command below to add a commit hook to your local Git
| |
− | repository that automatically adds Change-Id lines to your commits:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | scp -p -P 29418 $USERNAME@review.openstack.org:hooks/commit-msg .git/hooks/
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | Where ''$USERNAME'' is your Gerrit/Launchpad username.
| |
− | | |
− | The Gerrit manual goes into more detail about [https://review.openstack.org/Documentation/user-changeid.html change IDs].
| |
− | | |
− | ==== Pushing Changes from Git ====
| |
− | | |
− | To make pushing proposed changes to Gerrit easier, you should register
| |
− | Gerrit as a remote repository tracked by Git. Run the following
| |
− | command inside your local Git repository:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | git remote add gerrit ssh://$USERNAME@review.openstack.org:29418/openstack/$PROJECT.git
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | Where ''$USERNAME'' is the username you registered with Gerrit and
| |
− | ''$PROJECT'' is the name of the current project. Then when you are
| |
− | ready to push a change to Gerrit for review, you may issue a command
| |
− | like:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | git push gerrit HEAD:refs/for/master
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | To make pushing changes for review even easier, you should add a git
| |
− | alias. This is a global change which you only need to do once. Edit
| |
− | your '''~/.gitconfig''' file and add an alias like this:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | [alias]
| |
− | review = push gerrit HEAD:refs/for/master
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | From then on, pushing a change to gerrit is as simple as:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | git review
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | ==== 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. Any Openstack developer may propose or comment on a
| |
− | change (including voting +/-1 on it). Members of the core project team may
| |
− | mark changes as approved (by voting +2), which will immediately cause Jenkins to
| |
− | verify the change. 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.
| |
− | | |
− | = 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, Gerit, and Jenkins]
| |
− | in a similar manner (though with Gitorious instead of [[GitHub]]).
| |