|
|
| (152 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.
| |
| − | | |
| − | === 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 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 +/-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.
| |
| − | | |
| − | = 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]]).
| |
