Jump to: navigation, search

Difference between revisions of "Gerrit Workflow"

(added change-id hook line)
(Change link to https)
 
(118 intermediate revisions by 49 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.
 
</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]].
 

Latest revision as of 05:40, 5 December 2017

Please see the new Developer's Guide here: https://docs.openstack.org/infra/manual/developers.html