|
|
| (103 intermediate revisions by 40 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:
| |
| − | | |
| − | | |
| − | <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>
| |
