|
|
(116 intermediate revisions by 48 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 =
| |
− | | |
− | For a more complete description of the setup, see [[GerritJenkinsGithub]].
| |
− | | |
− | <<[[TableOfContents]]()>>
| |
− | | |
− | == Project Setup ==
| |
− | | |
− | 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.
| |
− | | |
− | Before setting up your first project, add a global git alias to make
| |
− | reviewing easier (you only have to do this once, not for each
| |
− | project):
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | cat <<EOF >>~/.gitconfig
| |
− | [alias]
| |
− | review = !sh \`git rev-parse --show-toplevel\`/tools/rfc.sh
| |
− | EOF
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | If you are going to contribute code to a project, run the following
| |
− | commands for each project you intend to work with.
| |
− | | |
− | To identify the list of available projects, run the following command:
| |
− | | |
− | <pre><nowiki>
| |
− | USERNAME=jsmith
| |
− | ssh -p29418 -o StrictHostKeyChecking=no $USERNAME@review.openstack.org gerrit ls-projects
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | Note: SSH public key should be updated to https://review.openstack.org/#settings,ssh-keys
| |
− | | |
− | As of Oct. 17, 2011, the list of available projects is:
| |
− | | |
− | <pre><nowiki>
| |
− | API-Projects
| |
− | All-Projects
| |
− | openstack-ci/git-review
| |
− | openstack/compute-api
| |
− | openstack/glance
| |
− | openstack/identity-api
| |
− | openstack/image-api
| |
− | openstack/keystone
| |
− | openstack/netconn-api
| |
− | openstack/nova
| |
− | openstack/object-api
| |
− | openstack/openstack-chef
| |
− | openstack/openstack-ci
| |
− | openstack/openstack-ci-puppet
| |
− | openstack/openstack-integration-tests
| |
− | openstack/openstack-manuals
| |
− | openstack/openstack-puppet
| |
− | openstack/quantum
| |
− | openstack/swift
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | Next, set these variables to the name of the project and your own
| |
− | username on Launchpad:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | PROJECT=nova
| |
− | USERNAME=jsmith
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | Then run the following commands to clone the repository and configure
| |
− | it for use with Gerrit:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | # Clone the repository
| |
− | git clone git://github.com/openstack/$PROJECT.git
| |
− | | |
− | # Set up the Gerrit Change-Id hook, and remote repository:
| |
− | scp -p -P 29418 $USERNAME@review.openstack.org:hooks/commit-msg .git/hooks
| |
− | cd $PROJECT
| |
− | git review
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | The command '''git review''' calls the global git alias you set up
| |
− | earlier. It invokes the script "tools/rfc.sh" which we maintain in
| |
− | each [[OpenStack]] repository. It makes sure that the Gerrit Change-Id
| |
− | hook is installed, the gerrit remote repository is configured, your
| |
− | changes are based on the tip of the master repository, and submits
| |
− | your changes with an appropriate topic.
| |
− | | |
− | For more information about how to use gerrit, please continue reading.
| |
− | | |
− | == 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>
| |
− | | |
− | | |
− | = Git Review Workflow =
| |
− | | |
− | This section describes the new recommendend workflow using the
| |
− | git-review tool, currently in testing. If you aren't testing
| |
− | git-review, please use the section above instead.
| |
− | | |
− | == 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:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | pip install git-review
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | == Project Setup ==
| |
− | | |
− | Clone a project in the usual way, for example:
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | 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.
| |
− | | |
− | == 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>
| |
− | | |
− | | |
− | == More details ? ==
| |
− | | |
− | See [[GerritJenkinsGithub]].
| |