|
|
| (157 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@gerrit.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 an SSH command to something like:
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | 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]]).
| |
