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 An optional set of wrapper scripts called [[GitGerrit]] are available to search
  22 gerrit from command line, fetch commits by the legacy gerrit number, and to
  23 assist in cherry picking commits to stable branches.
  24
  25 Master branch inclusion
  26 -----------------------
  27
  28 Generally, changes are accepted on a stable branch only after they have
  29 been merged onto the master branch.  Follow the instructions on
  30 [[GitDevelopers]] for information on how to submit changes to the master
  31 branch.
  32
  33
  34 Stable branch backport
  35 ----------------------
  36
  37 Once a change has been merged on the master branch, the change may be submitted
  38 to gerrit for the most recent stable branch (currently `openafs-stable-1_8_x`).
  39
  40 The change should be cherry-picked from the master branch (not gerrit). For
  41 changes which consist of multiple commits, each commit must be cherry-picked in
  42 the same order in which they were merged onto the master branch.
  43
  44 When cherry-picking commits, be sure to use the `-x` option so git will include
  45 the commit number in the new commit message, and use the `-e` option to open an
  46 editor during the cherry-pick to remove the Change-ID of the master branch
  47 commit.
  48
  49 Example:
  50
  51     git fetch origin
  52     git checkout origin/openafs-stable-1_8_x
  53     git cherry-pick -e -x origin/master~<number>
  54     <remove old Change-Id in the editor>
  55     git commit --amend
  56     git show
  57     <verify a new Change-Id has been added.>
  58
  59 Run `git commit --amend` immediately after each cherry-pick to verify the
  60 cherry-pick command has a new Change-ID.
  61
  62 Alternately, the [[GitGerrit]] git-gerrit-cherry-pick tool can be used to
  63 cherry pick by gerrit number and will automatically update the Change-Id
  64 in the commit message:
  65
  66 Example:
  67
  68     git fetch origin
  69     git checkout origin/openafs-stable-1_8_x
  70     git gerrit-cherry-pick <gerrit-number>
  71
  72 In the event the cherry-pick fails, due to code skew between the branches,
  73 it may be necessary to manually fix the merge conflict and run `git cherry-pick --continue`
  74 to complete the cherry pick. In this case, the `(cherry picked from commit...)`
  75 line will be missing and has to be added manually using `git commit --amend`.
  76
  77 After building and testing, the commit can be submitted to gerrit for the
  78 stable branch.
  79
  80 Example:
  81
  82     git push gerrit HEAD:refs/for/openafs-stable-1_8_x
  83
  84 Old Stable branch backport
  85 --------------------------
  86
  87 Once a change has been merged to the stable branch, the change may be submitted
  88 to gerrit for the old stable branch (currently `openafs-stable-1_6_x`).
  89
  90 Cherry pick the commit from the stable branch, not master, and not from gerrit.
  91
  92 Example:
  93
  94     git fetch origin
  95     git checkout origin/openafs-stable-1_6_x
  96     git cherry-pick -e -x origin/openafs-stable-1_8_x~<number>
  97
  98 Example with [[GitGerrit]]:
  99
 100     git fetch origin
 101     git checkout origin/openafs-stable-1_6_x
 102     git gerrit-cherry-pick <gerrit-number> --branch origin/openafs-stable-1_8_x
 103
 104 In the event the cherry-pick fails, due to code skew between the branches,
 105 it may be necessary to manually fix the merge conflict and run `git check-pick --continue`
 106 to complete the cherry pick. In this case, the `(cherry picked from commit...)`
 107 line will be missing and has to be added manually using `git commit --amend`.
 108
 109 After building and testing, the commit can be submitted to gerrit for the
 110 old stable branch.
 111
 112 Example:
 113
 114     git push gerrit HEAD:refs/for/openafs-stable-1_6_x
 115
 116 Avoiding Path Conflicts
 117 -----------------------
 118
 119 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.
 120
 121 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.
 122
 123 Alternatively, help get the "conflicting" change merged (or abandoned) before pushing your commit.
 124
 125 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!
 126
 127
 128 [1]: https://gerrit.openafs.org/