Firstly, if your machine doesn't already have it installed, get a copy of the 'git' version control system. This is available for many platforms from their upstream package repositories or, failing that, can be downloaded in both source and binary form from <http://git-scm.com/download>
-## <a name="Getting the _OpenAFS repository"></a> Getting the OpenAFS repository
+## <a name="Getting the _OpenAFS repository"></a> Getting the OpenAFS repository
You can download the entire OpenAFS repository by running
Note that this email address is the address by which you will be identified in [[OpenAFS]]'s revision history - it is also the address to which the gerrit code review tool will send all email related to the review of your code.
+If you plan on making changes to OpenAFS (and why else would you be reading this?) you should probably also grab <b>The change id hook</b> described in <b>Registering With gerrit</b> below. You can grab and apply the hook before registering, and it'll make sure your pre-registration development has the appropriate change IDs in the log. The hook only applies to your openafs development, so you're not going to mess up any of your non-OpenAFS work.
+
## <a name="Starting development"></a> Starting development
We strongly recommend that you do all of your development upon 'topic branches' This allows you to isolate multiple unrelated changes, and makes it easier to keep your tree in sync with the upstream [[OpenAFS]] one.
This puts me on a new branch, ready to start writing code. All new development should be based upon the origin/master branch, submissions based upon other branches are unlikely to be accepted, unless they address issues that are solely present in that branch.
-'git add' is used to tell git about any new files you create as part of your patch. If your patch results in any new compilation products (object files, new executables, etc) that git should not be tracking, please make sure that they're caught by the .gitignore mechanism. You can do this by checking that they don't appear in the output from 'git status'
+'git add' is used to tell git about any new files you create as part of your patch. If your patch results in any new compilation products (object files, new executables, etc) that git should not be tracking, please make sure that they're caught by the .gitignore mechanism. You can do this by checking that they don't appear in the output from 'git status'.
'git mv' and 'git rm' are used to move and delete files respectively.
(where SSH Username is what you were told on the the 'SSH Keys' page)
+### <a name="The change id hook"></a> The change id hook
+
+Gerrit introduces the concept of "change IDs". This is a unique reference for a particular change, which remains constant regardless of any changes that are made to the implementation. This allows a single reference to be attached to a given modification, irrespective of any rewrites that may occur as a result of review comments. Manually maintaining change Ids is a pain, so gerrit provides a git hook which can be used to automatically add a change Id to any new modifications you create.
+
+The hook can be downloaded from the [[OpenAFS]] gerrit server by running the following, in the top level of your git tree
+
+ scp -p -P 29418 gerrit.openafs.org:hooks/commit-msg .git/hooks/
+
## <a name="Uploading to gerrit"></a> Uploading to gerrit
When submitting to gerrit, it's important to realise that each commit in your branch will become a changeset in the upstream OpenAFS, typically with no modification at our end. It is therefore important that these commits follow some simple rules...
FIXES 123456
+Thirdly, each commit should have a valid changeID. Manually maintaining these is difficult and error prone, so we would strong advise that you install the changeID hook detailed earlier. This will automatically add a [[ChangeId]] line to your commit message if it doesn't already contain one.
+
Once you have commits in this form, use
git log -p origin/<branch>..HEAD
It's possible that your modifications won't be accepted first time. In this case, you need to revise your changes, and resubmit them to gerrit. Please note that this should always be done by modifying your original changeset, _not_ by submitting a new change that makes the required fixes. Either git commit --amend, or git rebase should be used to combine your changes with the original changeset, and then you should push this to gerrit with
git push ssh://gerrit.openafs.org/openafs.git <hash>:refs/changes/<number>
-
-(where <hash> is the sha1 hash of the revised change, and <number> is the change number you received when you originally submitted the patch)
+
+(where <hash> is the sha1 hash of the revised change that follows the word <tt>commit</tt> in the log message, and <number> is the change number you received when you originally submitted the patch)
You can obtain the sha1 hash of a commit by using 'git show' (if it is on the tip of your current branch), or 'git log' (if it is in your history)
You'll be presented with a list of patches requiring review or, if someone has asked, patches you've been explicitly requested to review. There are two types of review - Code Review and Verification. Code Review means that you have read through the code, and are satisified that it works properly, follows the tree's style, and generally doesn't suck. Verification means that you have taken a copy of the patch and tested it. We hope to eventually automate the verification step, but for now both must be perfomed by hand.
-To perform a code review, go through each of the diffs in the current changeset for the code you have decided to review. You can double click on a line to leave a comment. Once you have completed commenting, click on the 'Publish Comments' button on the page containing the list of patch sets. You will then be asked to score the patch, with a range from -1 to +1. -1 means that you don't think the code should be applied, +1 means that it is good to apply. You can also leave further, general, comments for the patch submitter.
+To perform a code review, go through each of the diffs in the current changeset for the code you have decided to review. You can double click on a line to leave a comment. Once you have completed commenting, click on the 'Review' button that's about 3/4 of the way down the page containing the list of patch sets. You will then be asked to score the patch, with a range from -1 to +1. -1 means that you don't think the code should be applied, +1 means that it is good to apply. You can also leave further, general, comments for the patch submitter.
Note that no matter how many +1 or -1 comments a patch receives, the gatekeepers can override these to either permit or forbid submission. Also, at least one gatekeeper must approve a patch before it can be submitted to the tree.
git://git.openafs.org / openafs-wiki.git / blobdiff