This page describes the procedure for contributing code changes to the OpenAFS
stable release series. Generally, only security fixes, bug fixes, and
-non-distributive features are accepted on stable branches.
+non-disruptive features are accepted on stable branches.
Contributions to the OpenAFS code base are generally first targeted to the git
`master` branch, which is considered the in-progress development branch. These
OpenAFS contributions are submitted to and reviewed on the [gerrit][1] review
system. See [[GitDevelopers]] for information on submitting changes to gerrit.
-Note that unlike most git based projects, OpenAFS developers have a adopted a
+Note that unlike most git based projects, OpenAFS developers have adopted a
linear commit history. Merge commits are generally avoided, and developers
generally run git rebase frequently before submitting changes to gerrit.
Master branch inclusion
-----------------------
-Generally, before changes are accepted on a stable branch only after they have
+Generally, changes are accepted on a stable branch only after they have
been merged onto the master branch. Follow the instructions on
[[GitDevelopers]] for information on how to submit changes to the master
branch.
When cherry-picking commits, be sure to use the `-x` option so git will include
the commit number in the new commit message, and use the `-e` option to open an
-editor during the cherry-pick to remove the gerrit id of the master branch
+editor during the cherry-pick to remove the Change-ID of the master branch
commit.
Example:
git checkout origin/openafs-stable-1_8_x
git cherry-pick -e -x origin/master~<number>
+Alternatively, you can run `git commit --amend` immediately after each
+cherry-pick to remove rhe Change-ID.
+
In the event the cherry-pick fails, due to code skew between the branches,
-it may be necessary to manually fix the merge conflict and run `git check-pick --continue`
-to complete the cherry pick.
+it may be necessary to manually fix the merge conflict and run `git cherry-pick --continue`
+to complete the cherry pick. In this case, the `(cherry picked from commit...)`
+line will be missing and has to be added manually using `git commit --amend`.
After building and testing, the commit can be submitted to gerrit for the
stable branch.
In the event the cherry-pick fails, due to code skew between the branches,
it may be necessary to manually fix the merge conflict and run `git check-pick --continue`
-to complete the cherry pick.
+to complete the cherry pick. In this case, the `(cherry picked from commit...)`
+line will be missing and has to be added manually using `git commit --amend`.
After building and testing, the commit can be submitted to gerrit for the
old stable branch.
git push gerrit HEAD:refs/for/openafs-stable-1_6_x
+Avoiding Path Conflicts
+-----------------------
+
+You make the life of the release manager/guardian/gatekeeper in charge of your
+change significantly easier by checking whether your change modifies a file
+which is also touched by an open change for the target branch, and if it does
+base your change on the already open change in question. That's even true
+if the changes are completely independent and a cherry-pick does not flag any
+conflicts, due to the way gerrit is configured. Obviously, it's even more true
+if the changes do conflict. An very good alternative is helping to get the other
+change either accepted or abandonded before you push yours.
[1]: https://gerrit.openafs.org/