|
|
(104 intermediate revisions by 41 users not shown) |
Line 1: |
Line 1: |
− | __NOTOC__
| + | Please see the new Developer's Guide here: https://docs.openstack.org/infra/manual/developers.html |
− | = Gerrit Workflow Quick Reference =
| |
− | | |
− | 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.
| |
− | | |
− | For a more complete description of the setup, see [[GerritJenkinsGithub]].
| |
− | | |
− | <<[[TableOfContents]]()>>
| |
− | == Account Setup ==
| |
− | Make sure you have a launchpad account, and you have uploaded your ssh
| |
− | public keys to it.
| |
− | | |
− | 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.
| |
− | | |
− | 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.
| |
− | | |
− | Ensure that you have run these steps to let git know about your email address:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | git config --global user.name "Firstname Lastname"
| |
− | git config --global user.email "your_email@youremail.com"
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | == Git Review Installation ==
| |
− | | |
− | We recommend using the "git-review" tool which is a git subcommand
| |
− | that handles all the details of working with Gerrit, the code review
| |
− | system used in [[OpenStack]] development. Before you start work, make
| |
− | sure you have git-review installed on your system.
| |
− | | |
− | On Ubuntu, or most other Unix-like systems, it is as simple as:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | pip install git-review
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | On Ubuntu Precise (12.04) and later, git-review is included in the distribution,
| |
− | so install it as any other package:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | apt-get install git-review
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | On Fedora 16 and later, git-review is included into the distribution,
| |
− | so install it as any other package:
| |
− | | |
− | NOTE: The package git-review is included in the repository "fedora-testing". You've to enable this repository manually in the file /etc/yum.repos.d/fedora-updates-testing.repo.
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | yum install git-review
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | On Fedora 15 and earlier, or on Red Hat Enterprise Linux, you have to
| |
− | install pip (its package name is `python-pip`), then install git-review
| |
− | using pip in a conventional way.
| |
− | | |
− | All of git-review's interactions with gerrit are sequences of normal git commands. If you want to know more about what it's doing, just add -v to the options and it will print out all of the commands it's running.
| |
− | | |
− | == Project Setup ==
| |
− | | |
− | Clone a project in the usual way, for example:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | git clone git://github.com/openstack/nova.git
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | You may want to ask git-review to configure your project to know about
| |
− | Gerrit at this point (though if you don't, it will do so the first
| |
− | time you submit a change for review). To do so (again, using Nova as
| |
− | an example):
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | cd nova
| |
− | git review -s
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | Git-review will check that you can log into gerrit with your ssh key.
| |
− | It assumes that your gerrit/launchpad username is the same as the
| |
− | current running user. If that doesn't work, it will ask for your
| |
− | gerrit/launchpad username.
| |
− | | |
− | If you get the error "We don't know where your gerrit is.", you will need to add a new git remote. The url should be in the error message. Copy that and create the new remote.
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | git remote add gerrit ssh://<username>@review.openstack.org:29418/openstack/nova.git
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | == Normal Workflow ==
| |
− | | |
− | Once your local repository is set up as above, you must use the
| |
− | following workflow.
| |
− | | |
− | Make sure you have the latest upstream changes:
| |
− | | |
− | <pre><nowiki>
| |
− | git remote update
| |
− | git checkout master
| |
− | git pull origin master
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | Create a [http://progit.org/book/ch3-4.html topic branch] to hold
| |
− | your work and switch to it. If you are working on a blueprint, name
| |
− | your topic branch '''bp/BLUEPRINT''' where BLUEPRINT is the name of a
| |
− | blueprint in launchpad (e.g., "bp/authentication"). Otherwise, give
| |
− | it a meaningful name because it will show up as the topic for your
| |
− | change in Gerrit.
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | git checkout -b TOPIC-BRANCH
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | === Committing Changes ===
| |
− | | |
− | Git commit messages should start with a short 50 character or less
| |
− | summary in a single paragraph. The following paragraph(s) should
| |
− | explain the change in more detail.
| |
− | | |
− | If your changes addresses a blueprint or a bug, be sure to mention
| |
− | them in the commit message using the following syntax:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | blueprint BLUEPRINT
| |
− | bug #######
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | e.g.:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | Adds keystone support.
| |
− | | |
− | Implements blueprint authentication. Fixes bug 123456.
| |
− | | |
− | (Long description of the change).
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | Make your changes, commit them, and submit them for review:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | git commit -a
| |
− | git review
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | | |
− | <pre><nowiki>#!wiki caution
| |
− | '''Note'''
| |
− | | |
− | Do not check in changes on your master branch. Doing so will cause
| |
− | merge commits when you pull new upstream changes, and merge commits
| |
− | will not be accepted by Gerrit.
| |
− | | |
− | Prior to checking in make sure that you run "./run_tests.sh -p"
| |
− | </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. You will start with the commit message
| |
− | from the commit that you picked, and it should have a Change-Id line
| |
− | in the message. Be sure to leave that Change-Id line in place when
| |
− | editing.
| |
− | | |
− | 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>
| |