From 03bcfb221efda69ffedd1ad2aa55bb914961b719 Mon Sep 17 00:00:00 2001
From: Michael Meffie <mmeffie@sinenomine.net>
Date: Wed, 25 Jul 2018 18:33:05 -0400
Subject: [PATCH] add backporting policy

---
 devel/Backporting.mdwn | 89 ++++++++++++++++++++++++++++++++++++++++++++++++++
 devel/index.mdwn       |  1 +
 2 files changed, 90 insertions(+)
 create mode 100644 devel/Backporting.mdwn

diff --git a/devel/Backporting.mdwn b/devel/Backporting.mdwn
new file mode 100644
index 0000000..f2f17f1
--- /dev/null
+++ b/devel/Backporting.mdwn
@@ -0,0 +1,89 @@
+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-distributive 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][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
+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
+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 gerrit 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>
+
+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.
+
+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>
+
+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.
+
+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
+
+
+[1]: https://gerrit.openafs.org/
diff --git a/devel/index.mdwn b/devel/index.mdwn
index 8d1d541..1f1d63d 100644
--- a/devel/index.mdwn
+++ b/devel/index.mdwn
@@ -1,6 +1,7 @@
 * [[AddOnsToolsAndUtilities]]
 * [[AFSServicePorts]]
 * [[AsyncRXProposal]]
+* [[Backporting]]
 * [[BinaryThirdParty]]
 * [[buildbotmasternotes]]
 * [[buildbot]]
-- 
1.9.4