AFSLore/GitGatekeepers.mdwn

   1 # <a name="Git and gerrit for gatekeepers"></a> Git and gerrit for gatekeepers
   2
   3 Firstly, please read the [[Git and gerrit for developers|Main/GitDevelopers]] document. This document only details gatekeeper specific workflow - it's worth reading the git basics first!
   4
   5 ## <a name="Getting started"></a> Getting started
   6
   7 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.
   8
   9 ## <a name="Commiting patches from RT (or el"></a> Commiting patches from RT (or elsewhere)
  10
  11 To commit a patch from RT, or elsewhere, make a new topic branch, and apply the patch to that branch.
  12
  13 When committing, use
  14
  15     git commit --author="A.N. Author <an.author@example.org>"
  16
  17 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 ...
  18
  19 ## <a name="Perfoming Reviews"></a> Perfoming Reviews
  20
  21 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.
  22
  23 ## <a name="Submitting the patch"></a> Submitting the patch
  24
  25 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.
  26
  27 ## <a name="Creating a delta name"></a> Creating a delta name
  28
  29 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>
  30
  31 If you're scared of web interfaces, you can also do this by hand. Log in to openafs.stanford.edu and do
  32
  33     cd /srv/git/openafs.git
  34     git update-ref refs/deltas/<branch>/<delta-name> <sha1>
  35
  36 Where &lt;branch&gt; is the branch of the commit you wish to name, &lt;delta-name&gt; is the name you wish to give it, and &lt;sha1&gt; 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)
  37
  38 ## <a name="Performing pullups"></a> Performing pullups
  39
  40 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
  41
  42     git cherry-pick -x deltas/<branch>/<delta-name>
  43
  44 If the cherry pick fails for some reason, you may need to extract the patch
  45
  46     git show deltas/<branch>/<delta-name>
  47
  48 and apply it by hand, commiting it as you would for a normal change.
  49
  50 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...
  51
  52 ## <a name="Dealing with conflicts"></a> Dealing with conflicts
  53
  54 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.
  55
  56     git fetch
  57     git checkout -b <new-topic-branch>
  58     git cherry-pick <sha1 of contribution>
  59
  60 The cherry-pick will give you a warning like
  61
  62     Automatic cherry-pick failed.  After resolving the conflicts,
  63     mark the corrected paths with 'git add <paths>' or 'git rm <paths>' and commit the result.
  64     When commiting, use the option '-c 822e735' to retain authorship and message.
  65
  66 if it fails. At this point, resolve the conflict. You can use git diff to determine what it is. Then, continue:
  67
  68     git add <file with resolved conflict> [<next file with resolved conflict>]
  69     git commit -c <commit hash from cherry pick>
  70
  71 Confirm you will push the right thing:
  72
  73     git log -p origin/master..HEAD
  74
  75 Then, push the change back to the open issue in gerrit.
  76
  77     git push ssh://gerrit.openafs.org/openafs <hash>:refs/changes/<gerrit change number>
  78
  79 ## <a name="Bypassing Gerrit"></a> Bypassing Gerrit
  80
  81 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/&lt;branch&gt;, rather than refs/for/&lt;branch&gt;, gerrit will simply apply them directly to the tree.
  82
  83 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.
  84
  85 ## <a name="Modifying a change in gerrit"></a> Modifying a change in gerrit
  86
  87 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.
  88
  89 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
  90
  91     git commit --amend --author "A.N. Author <a.n.author@example.org>"
  92
  93 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)
  94
  95 ## <a name="Making a release"></a> Making a release
  96
  97 I'll document this when the release tool is done. Should be sometime before the next release ...
  98
  99 -- [[SimonWilkinson]] - 08 Jul 2009