devel/Backporting.mdwn

   1 Backporting changes for OpenAFS
   2 ===============================
   3
   4 This page describes the procedure for contributing code changes to the OpenAFS
   5 stable release series. Generally, only security fixes, bug fixes, and
   6 non-disruptive features are accepted on stable branches.
   7
   8 Contributions to the OpenAFS code base are generally first targeted to the git
   9 `master` branch, which is considered the in-progress development branch. These
  10 changes will be included in a future release when the OpenAFS release team
  11 creates a stable branch point for a new major release.  Changes for the current
  12 stable branches generally require a backporting process. This is intended to
  13 reduce the chance of losing important changes between the branches.
  14
  15 OpenAFS contributions are submitted to and reviewed on the [gerrit][1] review
  16 system.  See [[GitDevelopers]] for information on submitting changes to gerrit.
  17 Note that unlike most git based projects, OpenAFS developers have adopted a
  18 linear commit history. Merge commits are generally avoided, and developers
  19 generally run git rebase frequently before submitting changes to gerrit.
  20
  21
  22 Master branch inclusion
  23 -----------------------
  24
  25 Generally, changes are accepted on a stable branch only after they have
  26 been merged onto the master branch.  Follow the instructions on
  27 [[GitDevelopers]] for information on how to submit changes to the master
  28 branch.
  29
  30
  31 Stable branch backport
  32 ----------------------
  33
  34 Once a change has been merged on the master branch, the change may be submitted
  35 to gerrit for the most recent stable branch (currently `openafs-stable-1_8_x`).
  36
  37 The change should be cherry-picked from the master branch (not gerrit). For
  38 changes which consist of multiple commits, each commit must be cherry-picked in
  39 the same order in which they were merged onto the master branch.
  40
  41 When cherry-picking commits, be sure to use the `-x` option so git will include
  42 the commit number in the new commit message, and use the `-e` option to open an
  43 editor during the cherry-pick to remove the Change-ID of the master branch
  44 commit.
  45
  46 Example:
  47
  48     git fetch origin
  49     git checkout origin/openafs-stable-1_8_x
  50     git cherry-pick -e -x origin/master~<number>
  51
  52 Alternatively, you can run `git commit --amend` immediately after each
  53 cherry-pick to remove rhe Change-ID.
  54
  55 In the event the cherry-pick fails, due to code skew between the branches,
  56 it may be necessary to manually fix the merge conflict and run `git cherry-pick --continue`
  57 to complete the cherry pick. In this case, the `(cherry picked from commit...)`
  58 line will be missing and has to be added manually using `git commit --amend`.
  59
  60 After building and testing, the commit can be submitted to gerrit for the
  61 stable branch.
  62
  63 Example:
  64
  65     git push gerrit HEAD:refs/for/openafs-stable-1_8_x
  66
  67 Old Stable branch backport
  68 --------------------------
  69
  70 Once a change has been merged to the stable branch, the change may be submitted
  71 to gerrit for the old stable branch (currently `openafs-stable-1_6_x`).
  72
  73 Cherry pick the commit from the stable branch, not master, and not from gerrit.
  74
  75 Example:
  76
  77     git fetch origin
  78     git checkout origin/openafs-stable-1_6_x
  79     git cherry-pick -e -x origin/openafs-stable-1_8_x~<number>
  80
  81 In the event the cherry-pick fails, due to code skew between the branches,
  82 it may be necessary to manually fix the merge conflict and run `git check-pick --continue`
  83 to complete the cherry pick. In this case, the `(cherry picked from commit...)`
  84 line will be missing and has to be added manually using `git commit --amend`.
  85
  86 After building and testing, the commit can be submitted to gerrit for the
  87 old stable branch.
  88
  89 Example:
  90
  91     git push gerrit HEAD:refs/for/openafs-stable-1_6_x
  92
  93 Avoiding Path Conflicts
  94 -----------------------
  95
  96 You make the life of the release manager/guardian/gatekeeper in charge of your
  97 change significantly easier by checking whether your change modifies a file
  98 which is also touched by an open change for the target branch, and if it does
  99 base your change on the already open change in question. That's even true
 100 if the changes are completely independent and a cherry-pick does not flag any
 101 conflicts, due to the way gerrit is configured. Obviously, it's even more true
 102 if the changes do conflict. An very good alternative is helping to get the other
 103 change either accepted or abandonded before you push yours.
 104
 105 [1]: https://gerrit.openafs.org/