|
|
(155 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]]()>>
| |
− | | |
− | = 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.
| |
− | | |
− | === Register for an Account with Gerrit ===
| |
− | | |
− | Visit https://review.openstack.org/ and click the '''Register''' link
| |
− | at the top-right corner of the page. Log in with your Launchpad ID,
| |
− | which looks like:
| |
− | | |
− | https://launchpad.net/~USERNAME
| |
− | | |
− | Where ''USERNAME'' is your Launchpad username. Because Gerrit uses
| |
− | OpenID, you won't need a separate password for Gerrit. As part of the
| |
− | registration process, you will need to upload your SSH public key.
| |
− | You may have already done this when registering with Launchpad, if so you
| |
− | may use the same key. See
| |
− | [https://review.openstack.org/Documentation/user-upload.html#_ssh the Gerrit manual] for more
| |
− | information.
| |
− | | |
− | When Gerrit asks you to choose a username, choose the same one you use
| |
− | on Launchpad.
| |
− | | |
− | | |
− | <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. Additionally, we hope to automatically sync
| |
− | Gerrit accounts, groups, and SSH keys from Launchpad in the near
| |
− | future so developers will be able to skip this step.
| |
− | </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 adds a '''Change-Id''' header to commits so that it can link
| |
− | Git commits to changes stored in its database. It will add it
| |
− | automatically if not present, but frequent Gerrit users may want to
| |
− | have the header added locally before being uploaded to Gerrit. In
| |
− | particular, this will make updating patches for existing changes
| |
− | easier. To cause the Change-Id header to be added automatically to
| |
− | each commit message, run this command inside your repository:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | scp -p -P 29418 USERNAME@review.openstack.org:hooks/commit-msg .git/hooks/
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | Where ''USERNAME'' is the username you registered with Gerrit.
| |
− | | |
− | ==== Git Remote ====
| |
− | | |
− | To make pushing proposed changes to Gerrit easier, you may 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>
| |
− | | |
− | | |
− | ==== 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 on it). Members of the core project team may
| |
− | mark changes as approved (by voting +2), and once a change has at
| |
− | least one +2 vote, no -2 votes, and Jenkins has tested the change and
| |
− | verified it, the change can be submitted by a member of the core
| |
− | developer group to be merged into the repository.
| |
− | | |
− | = 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]]).
| |