add backporting policy
[openafs-wiki.git] / 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-distributive 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 a 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, before 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 gerrit 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 In the event the cherry-pick fails, due to code skew between the branches,
53 it may be necessary to manually fix the merge conflict and run `git check-pick --continue`
54 to complete the cherry pick.
55
56 After building and testing, the commit can be submitted to gerrit for the
57 stable branch.
58
59 Example:
60
61     git push gerrit HEAD:refs/for/openafs-stable-1_8_x
62
63 Old Stable branch backport
64 --------------------------
65
66 Once a change has been merged to the stable branch, the change may be submitted
67 to gerrit for the old stable branch (currently `openafs-stable-1_6_x`).
68
69 Cherry pick the commit from the stable branch, not master, and not from gerrit.
70
71 Example:
72
73     git fetch origin
74     git checkout origin/openafs-stable-1_6_x
75     git cherry-pick -e -x origin/openafs-stable-1_8_x~<number>
76
77 In the event the cherry-pick fails, due to code skew between the branches,
78 it may be necessary to manually fix the merge conflict and run `git check-pick --continue`
79 to complete the cherry pick.
80
81 After building and testing, the commit can be submitted to gerrit for the
82 old stable branch.
83
84 Example:
85
86     git push gerrit HEAD:refs/for/openafs-stable-1_6_x
87
88
89 [1]: https://gerrit.openafs.org/