Backporting changes for OpenAFS

This page describes the procedure for contributing code changes to the OpenAFS stable release series. Generally, only security fixes, bug fixes, and 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 changes will be included in a future release when the OpenAFS release team creates a stable branch point for a new major release. Changes for the current stable branches generally require a backporting process. This is intended to reduce the chance of losing important changes between the branches.

OpenAFS contributions are submitted to and reviewed on the gerrit review system. See GitDevelopers for information on submitting changes to gerrit. 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.

An optional set of wrapper scripts called GitGerrit are available to search gerrit from command line, fetch commits by the legacy gerrit number, and to assist in cherry picking commits to stable branches.

Master branch inclusion

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.

Stable branch backport

Once a change has been merged on the master branch, the change may be submitted to gerrit for the most recent stable branch (currently openafs-stable-1_8_x).

The change should be cherry-picked from the master branch (not gerrit). For changes which consist of multiple commits, each commit must be cherry-picked in the same order in which they were merged onto 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 Change-ID of the master branch commit.

Example:

git fetch origin
git checkout origin/openafs-stable-1_8_x
git cherry-pick -e -x origin/master~<number>
<remove old Change-Id in the editor>
git commit --amend
git show
<verify a new Change-Id has been added.>

Run git commit --amend immediately after each cherry-pick to verify the cherry-pick command has a new Change-ID.

Alternately, the GitGerrit git-gerrit-cherry-pick tool can be used to cherry pick by gerrit number and will automatically update the Change-Id in the commit message:

Example:

git fetch origin
git checkout origin/openafs-stable-1_8_x
git gerrit-cherry-pick <gerrit-number>

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 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.

Example:

git push gerrit HEAD:refs/for/openafs-stable-1_8_x

Old Stable branch backport

Once a change has been merged to the stable branch, the change may be submitted to gerrit for the old stable branch (currently openafs-stable-1_6_x).

Cherry pick the commit from the stable branch, not master, and not from gerrit.

Example:

git fetch origin
git checkout origin/openafs-stable-1_6_x
git cherry-pick -e -x origin/openafs-stable-1_8_x~<number>

Example with GitGerrit:

git fetch origin
git checkout origin/openafs-stable-1_6_x
git gerrit-cherry-pick <gerrit-number> --branch origin/openafs-stable-1_8_x

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. 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.

Example:

git push gerrit HEAD:refs/for/openafs-stable-1_6_x

Avoiding Path Conflicts

Due to the way gerrit is configured, it may claim that one of your commits has a "Merge conflict" if it modifies any file that also has changes in other gerrits under review for that branch. That's even true if the changes are completely independent, and a cherry-pick does not flag any conflicts.

Before submitting, check the other open gerrits for that branch for modifications to the same files you are modifying. If you find any, please base your change on top of those open changes before submission.

Alternatively, help get the "conflicting" change merged (or abandoned) before pushing your commit.

Your efforts in avoiding "Merge conflicts" in this way will make the life of the release manager/guardian/gatekeeper in charge of your change significantly easier. Thank you!