Git and gerrit for gatekeepers

Firstly, please read the Git and gerrit for developers document. This document only details gatekeeper specific workflow - it's worth reading the git basics first!

Also read the Maintainers and Approvals policy that covers expectations for what reviews are performed before merging changes.

Getting started

Log in to gerrit, create yourself a ssh key, set up your preferred email addresses, clone a local tree, and tell git who you are as detailed in the developers document. Email Simon (or a gatekeeper who's already got an account) the ?OpenID you created your account with, and they'll grant gatekeeper permissions.

Commiting patches from RT (or elsewhere)

To commit a patch from RT, or elsewhere, make a new topic branch, and apply the patch to that branch.

When committing, use

git commit --author="A.N. Author <an.author@example.org>"

to acknowledge the patch author (your name will still be there as the committer of the patch). Push the patch into gerrit as usual, and wait for reviews ...

Perfoming Reviews

Because gatekeepers are special, you have a wider range of review options. In addition to scoring +1 to -1, you can also score +2 and -2. A +2 means that the patch can be submitted. A -2 means that the patch is rejected. Note that these scores are not additive (2 +1s do not make a +2, 4 +1s don't cancel out a -2). This means that gatekeeper's scores are definitive - it doesn't matter what others may score, although that should probably be used as a guide.

Submitting the patch

Once a patch has both a +2 code review, and has verified OK, it may be submitted (note that you can apply these to your own patch, so gatekeepers can bypass code review with a few clicks). A Submit button will appear on the patch's gerrit page - when clicked, the patch will be pushed into the git tree.

Creating a delta name

Eventually, we hope that gerrit will support prompting for a delta name as part of the patch submission process. Sadly, we're not there yet, so there is a separate web interface to use for this at http://git.openafs.org/deltas/edit

If you're scared of web interfaces, you can also do this by hand. Log in to openafs.stanford.edu and do

cd /srv/git/openafs.git
git update-ref refs/deltas/<branch>/<delta-name> <sha1>

Where <branch> is the branch of the commit you wish to name, <delta-name> is the name you wish to give it, and <sha1> is the hash gerrit gave to the commit, as reported in the gerrit submit message ( NB This will be different from the sha1 of the commit in your local tree, or in the refs/changes entry, as we current cherry-pick commits upon submission)

Performing pullups

A patch can be pulled up (in a tree which contains deltas - see the developers guide) by simply checking out the destination branch, and running

git cherry-pick -x deltas/<branch>/<delta-name>

If the cherry pick fails for some reason, you may need to extract the patch

git show deltas/<branch>/<delta-name>

and apply it by hand, commiting it as you would for a normal change.

You can then push this patch to gerrit as normal, if you wish. However, note that this push will simply put the patch in the review queue again. Another way in which gatekeepers are special is that you can bypass gerrit...

Dealing with conflicts

You may find that attempting to cherry-pick a patch via gerrit results in a conflict. One way to address this is to modify the commit. Start with a current repository, cherry-pick the commit, fix it, and push back to gerrit.

git fetch
git checkout -b <new-topic-branch>
git cherry-pick <sha1 of contribution>

The cherry-pick will give you a warning like

Automatic cherry-pick failed.  After resolving the conflicts,
mark the corrected paths with 'git add <paths>' or 'git rm <paths>' and commit the result.
When commiting, use the option '-c 822e735' to retain authorship and message.

if it fails. At this point, resolve the conflict. You can use git diff to determine what it is. Then, continue:

git add <file with resolved conflict> [<next file with resolved conflict>]
git commit -c <commit hash from cherry pick>

Confirm you will push the right thing:

git log -p origin/master..HEAD

Then, push the change back to the open issue in gerrit.

git push ssh://gerrit.openafs.org/openafs <hash>:refs/changes/<gerrit change number>

Bypassing Gerrit

Should you wish to push a patch directly into the git tree, without having that patch reviewed, you can do so. By pushing your changes to refs/heads/<branch>, rather than refs/for/<branch>, gerrit will simply apply them directly to the tree.

Note that having done a pullup, or a direct commit, you will need to visit the web page to tag it as a delta. Sorry. I'll make this better soon, honest.

Modifying a change in gerrit

The typical gerrit workflow expects that instead of gatekeepers modifying changes in gerrit, they will simply leave review comments and expect the committer to fix their patch to address those comments themselves (the theory being that this educates the committers, and thus reduces the load on the gatekeepers in the long term). However, if you want to modify someone's change, you can do so.

Simply fetch the change from gerrit as if you were going to verify it (as documented in the developers guide), making sure that you do that fetch into a topic branch. Then, make your modifications and run

git commit --amend --author "A.N. Author <a.n.author@example.org>"

Then push this commit into gerrit as a replacement from the original change (again, see the developers guide for details of exactly how to do this)

Making a release

I'll document this when the release tool is done. Should be sometime before the next release ...

-- Simon Wilkinson - 08 Jul 2009