|
|
| (143 intermediate revisions by 57 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 TOPIC-BRANCH
| |
| − | git checkout TOPIC-BRANCH
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | Make your changes, commit them, and submit them for review:
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | git commit -a
| |
| − | git review
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | === Long-lived Topic Branches ===
| |
| − | | |
| − | 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:
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | git checkout master
| |
| − | git pull origin master
| |
| − | git checkout TOPIC-BRANCH
| |
| − | git rebase -i master
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | Use the editor to squash any commits that should not appear in the public history. If you want one change to be submitted to Gerrit, you should only have one "pick" line at the end of this process. After completing this, you will be able to prepare your public commit message(s) in your editor. Once the commit history in your branch looks correct, run '''git review''' to submit your changes to Gerrit.
| |
| − | | |
| − | === 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.
| |
| − | | |
| − | 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 on it). Members of the core project team may
| |
| − | mark changes as approved (by voting +2).
| |
| − | | |
| − | Once a review is voted up to +2 (two reviewers, or one core-team reviewer
| |
| − | voting +2), 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.
| |
| − | | |
| − | = 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]]).
| |
