-Git opens up a number of new options for contributing to OpenAFS. For the first time, it is easy to review code that is pending addition to the OpenAFS tree. In fact, reviewing code is one of the best ways to ensure that the releases that OpenAFS ships remain stable and functional. If you are interested purely in reviewing, then please skip to that section towards the end of this document.
-
-Git also changes the way that developers interact with the OpenAFS tree. Instead of just having a single version of the tree on your local machine, you have a compressed copy of the entire repository. Additionally, you no longer have to produce patches to send code upstream - any developer can push into the OpenAFS repository directly, through gerrit, our code review tool.
-
-Whilst git is a far more powerful tool than CVS it is also, inevitably, more complex. This document can only scratch the surface of what's possible with git - there are many, many, documents available that describe git in greater detail, and references to some of them are provided at the end.
+Git opens up a number of new options for contributing to OpenAFS. For the first
+time, it is easy to review code that is pending addition to the OpenAFS tree.
+In fact, reviewing code is one of the best ways to ensure that the releases
+that OpenAFS ships remain stable and functional. If you are interested purely
+in reviewing, then please skip to that section towards the end of this
+document.
+
+Git also changes the way that developers interact with the OpenAFS tree.
+Instead of just having a single version of the tree on your local machine, you
+have a compressed copy of the entire repository. Additionally, you no longer
+have to produce patches to send code upstream - any developer can push into the
+OpenAFS repository directly, through gerrit, our code review tool.
+
+Whilst git is a far more powerful tool than CVS it is also, inevitably, more
+complex. This document can only scratch the surface of what's possible with git
+- there are many, many, documents available that describe git in greater
+detail, and references to some of them are provided at the end.
## <a name="Getting git"></a> Getting git
git checkout openafs-stable-1_4_10
-Again, whilst a direct checkout of a remote tag is fine for code browsing, it should not be used as a place to start development. If you must do development against a tag, then create a local topic branch with it as a starting point, as is discussed below. However, in general, please don't develop from a particular tag, but instead work from a branch tip. It makes it much easier to integrate your changes!
+Again, whilst a direct checkout of a remote tag is fine for code browsing, it
+should not be used as a place to start development. If you must do development
+against a tag, then create a local topic branch with it as a starting point, as
+is discussed below. However, in general, please don't develop from a particular
+tag, but instead work from a branch tip. It makes it much easier to integrate
+your changes!
## <a name="Viewing deltas"></a> Viewing deltas
-OpenAFS's original CVS repository used the concept of deltas as a means of grouping a large number of related changes into a single item, which could be easily fetched and referred to. In git, a delta should be simply a single commit. Deltas are represented by means of a special form of git tag, allowing you to locally view the change and commit message that corresponds to each one. In order to keep down the transfer size, deltas are not included in the repository you get when you do a git clone - there are over 10,000 delta references, and having them in your local repository can cause performance issues. If you really wish to be able to locally browse deltas, then run the following
+OpenAFS's original CVS repository used the concept of deltas as a means of
+grouping a large number of related changes into a single item, which could be
+easily fetched and referred to. In git, a delta should be simply a single
+commit. Deltas are represented by means of a special form of git tag, allowing
+you to locally view the change and commit message that corresponds to each one.
+In order to keep down the transfer size, deltas are not included in the
+repository you get when you do a git clone - there are over 10,000 delta
+references, and having them in your local repository can cause performance
+issues. If you really wish to be able to locally browse deltas, then run the
+following
git config --add remote.origin.fetch '+refs/deltas/*:refs/remotes/deltas/*'
git fetch origin
git show refs/remotes/deltas/<branch>/<delta>
-Sadly, historical accidents mean that not all of our deltas can be represented by means of single commit. Where this is the case, a delta-name will have a trailing -part-, where each of these numbers must be used to form the complete delta. This only applies to some deltas created before the git conversion - all deltas created from now on will be single commits.
+Sadly, historical accidents mean that not all of our deltas can be represented
+by means of single commit. Where this is the case, a delta-name will have a
+trailing -part-, where each of these numbers must be used to form the complete
+delta. This only applies to some deltas created before the git conversion - all
+deltas created from now on will be single commits.
## <a name="Introducing yourself to git"></a> Introducing yourself to git
-Before you begin development, you should let git know who you are. This provides it with a name, and email address, that is used to attribute all commits in your repository, and in any that you share code with.
+Before you begin development, you should let git know who you are. This
+provides it with a name, and email address, that is used to attribute all
+commits in your repository, and in any that you share code with.
git config user.name "Joe Bloggs"
git config user.email "joe.bloggs@example.org"
git config --global user.name "Joe Bloggs"
git config --global user.email "joe.bloggs@example.org"
-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.
+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.
+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="Helpful git tips"></a> Helpful git tips
## <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.
+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.
Before creating a new topic branch, running
If you can't rebase, then consider either merging the changes onto your local branch, or creating a new topic branch and cherry picking your changes onto it. The man pages for 'git merge' and 'git cherry-pick' provide more detail on these options.
-Pour sécuriser efficacement les archives et documents papiers importants, l'idéal est d'utiliser une bonne [armoire forte réfractaire](http://www.infosafe.fr/Armoirefortedin/Armoirefortedin.htm) fixée au sol
-
## <a name="Sharing your code with us"></a> Sharing your code with us
How you work from this point onwards depends on how you intend making your code available to OpenAFS. We're still happy to receive submission by patch (by sending your changes to <openafs-bugs@openafs.org>), but it makes it much easier for us if you push directly from your git tree to our code review system, gerrit.
First, each commit should be complete. The maxim "one change per commit, one commit per change" applies here. Each commit should build and test in its own right. Typically, this means that a change will be in a small number of commits. If, during development, you have created many more than this (for example, you've created a large number of bug fix commits), please use 'git rebase', or cherry pick these commits into a separate tree before uploading them. Note, however, that "one change" could equate to a change to source code and a change to the corresponding documentation for that code specific change.
-Secondly, each commit should have a meaningful revision log. The internals of git means that we can't easily edit these before pushing them into the tree, so we'd like you to get them right for us! A commit message should be comprised of a single 'subject' line (which must **not** end with a full stop), followed by a blank line, followed by one or more paragraphs explaining the purpose of the patch. If it is intended to fix a bug in OpenAFS RT, then the word 'FIXES' followed by the bug number or comma-separated list of bug numbers should be included on a line of its own. The 'LICENSE' keyword can be used to indicate code which is covered under a license other than the IPL, although please speak to a gatekeeper if you intend using this. An example commit message would be
+Secondly, each commit should have a meaningful revision log. The internals of git means that we can't easily edit these before pushing them into the tree, so we'd like you to get them right for us! A commit message should be comprised of a single 'subject' line (which must **not** end with a full stop), followed by a blank line, followed by one or more paragraphs explaining the purpose of the patch. Gerrit warns if the 'subject' is longer than 65 characters. If it is intended to fix a bug in OpenAFS RT, then the word 'FIXES' followed by the bug number or comma-separated list of bug numbers should be included on a line of its own. The 'LICENSE' keyword can be used to indicate code which is covered under a license other than the IPL, although please speak to a gatekeeper if you intend using this. An example commit message would be
Add option to disable syscall probing
git config --global config.cleanup whitespace
+Then commit your changes, for example with a file that contains your log message
+
+ git commit -a -F <your-log-message-in-this-file>
+
+(where <your-log-message-in-this-file> is a file with the log message)
+
Once your commits have a proper commit message and have all whitespace errors fixed, use
git log -p origin/<branch>..HEAD
After you have resolved all conflicts and are once again happy with the commit, simply resubmit your change in the same way as if you had been asked to revise it (see notes above)
+## <a name="Pulling up a change to a stable branch"></a> Pulling Up a Change to a Stable Branch
+
+After a change has passed through the Gerrit Code Review process it will be merged onto the <tt>master</tt> branch of the OpenAFS repository. The merged commit will then become visible in your local repository the next time a
+
+ git pull
+
+command is executed. OpenAFS releases are not issued from the <tt>master</tt> branch. Instead releases such as <tt>1.6.11</tt> are issued from stable branches such as <tt>openafs-stable-1_6_x</tt>. After a change is approved on <tt>master</tt> the change must be pulled up to the stable branch, be modified for any differences between <tt>master</tt> and <tt>openafs-stable-N_N_x</tt> and be resubmitted to Gerrit.
+
+Start by checking out the stable branch of interest. For example, if you want to submit a change to the next 1.6 series release you would first checkout <tt>master</tt>.
+
+ git checkout --track origin/master
+
+or just
+
+ git checkout master
+
+if you have already created the tracking branch. Then
+
+ git pull
+
+to import any new changes to the local repository and fast-forward <tt>HEAD</tt> to the most recent commit merged onto <tt>origin/master</tt>. It is important to note that if any local changes were committed onto the local <tt>master</tt> tracking branch that a fast-forward operation will not occur. Instead the local changes and the changes to origin will be merged producing a merge commit. A merge commit is not compatible with the OpenAFS management of the git repository. To rebase local changes onto of the <tt>HEAD</tt> of <tt>origin/master</tt> the command
+
+ git pull --rebase
+
+can be performed. If there are conflicts when applying the local changes to current <tt>HEAD</tt> of <tt>origin/master</tt> you will have an opportunity to resolve them.
+
+Once the change you wish to pullup to the stable branch is in the local repository you can use
+
+ git log master
+
+to find it and record the sha1 identifier for the commit. Now you are ready to switch to the stable branch for example, <tt>openafs-stable-1_6_x</tt>. If you do not already have a local tracking branch execute
+
+ git checkout --track origin/<stable-branch>
+
+and if you do then execute
+
+ git checkout <stable-branch>
+
+After switching branches you might be told that the local branch is behind the <tt>origin</tt>. If so, execute
+
+ git pull
+
+to fast-forward the branch <tt>HEAD</tt> to the most recent commit. Now you can pull the commit from <tt>master</tt> by using performing a cherry-pick:
+
+ git cherry-pick -x <sha1>
+
+This will create a new commit on the current branch with a commit message that has been modified with
+
+ (cherry picked from commit <sha1>)
+
+This commit message will include the <tt>Change-Id</tt> from the original submission to Gerrit. It is important that the <tt>Change-Id</tt> values submitted to Gerrit be unique but Gerrit will not enforce this. You <b>must</b> remember to edit the commit message and remove the old <tt>Change-Id</tt> using
+
+ git commit --amend
+
+so that the Change ID Hook will generate a new <tt>Change-Id</tt> before pushing the change to Gerrit.
+
+Once the commit message has been ammended and any other required changes are made it is time to push the change to Gerrit:
+
+ git push ssh://gerrit.openafs.org/openafs.git HEAD:refs/for/<stable-branch>/<topic>
+
+The change will then be evaluated by the OpenAFS Release team for incorporation into a future stable release.
+
## <a name="Submitting by patch"></a> Submitting by patch
If all of this seems too daunting (and please don't let it put you off) you can still, of course, submit patches by email.
Gerrit Documentation <http://gerrit.googlecode.com/svn/documentation/2.0/index.html> (only the first 'User Guide' section of this document is relevant)
+
+
Five advanced Git merge techniques <http://blog.ezyang.com/2010/01/advanced-git-merge/>
## <a name="Acknowledgments"></a> Acknowledgments
git://git.openafs.org / openafs-wiki.git / blobdiff