Help/dev: Document "Backport:" footer for MR descriptions

2 files changed, 32 insertions, 3 deletions

diff --git a/Help/dev/maint.rst b/Help/dev/maint.rst
index 44e2273..a1c1a6f 100644
--- a/Help/dev/maint.rst
+++ b/Help/dev/maint.rst
@@ -14,6 +14,11 @@ Review a Merge Request
 The `CMake Review Process`_ requires a maintainer to issue the ``Do: merge``
 command to integrate a merge request.  Please check at least the following:
 
+* If the MR source branch (or part of it) should be backported
+  to the ``release`` branch (and is already based on a commit
+  contained in the ``release`` branch), add a ``Backport: release`` or
+  ``Backport: release:<commit-ish>`` trailing line to the MR description.
+
 * If the MR source branch is not named well for the change it makes
   (e.g. it is just ``master`` or the patch changed during review),
   add a ``Topic-rename: <topic>`` trailing line to the MR description
@@ -38,9 +43,10 @@ command to integrate a merge request.  Please check at least the following:
   of various nightly builders.)
 
 * Ensure that the MR targets the ``master`` branch.  A MR intended for
-  the ``release`` branch should be based on ``release`` but still merged
-  to ``master`` first (via ``Do: merge``).  A maintainer may then merge
-  the MR topic to ``release`` manually.
+  the ``release`` branch should be based on ``release`` but still target
+  ``master``.  Use the above-mentioned ``Backport: release`` line to tell
+  ``Do: merge`` to merge to both.  If a MR is merged without the backport
+  line, a maintainer may still merge the MR topic to ``release`` manually.
 
 Maintain Current Release
 ========================
@@ -51,6 +57,12 @@ using a local branch named ``release-$ver``, where ``$ver`` is the version
 number of the current release in the form ``$major.$minor``.  It is always
 merged into ``master`` before publishing.
 
+To merge an open MR to the ``release`` branch, edit its description to
+use the ``Backport: release`` line mentioned above and then ``Do: merge``
+normally.  To update the ``release`` branch manually (e.g. to merge a
+``$topic`` branch that was merged without the backport line), use the
+following procedure.
+
 Before merging a ``$topic`` branch into ``release``, verify that the
 ``$topic`` branch has already been merged to ``master`` via the usual
 ``Do: merge`` process.  Then, to merge the ``$topic`` branch into
diff --git a/Help/dev/review.rst b/Help/dev/review.rst
index 36b9789..8ec41d2 100644
--- a/Help/dev/review.rst
+++ b/Help/dev/review.rst
@@ -433,6 +433,21 @@ Additionally, ``Do: merge`` extracts configuration from trailing lines
 in the MR description (the following have no effect if used in a MR
 comment instead):
 
+* ``Backport: release[:<commit-ish>]``: merge the topic branch into
+  the ``release`` branch to backport the change.  This is allowed
+  only if the topic branch is based on a commit in ``release`` already.
+  If only part of the topic branch should be backported, specify it as
+  ``:<commit-ish>``.  The ``<commit-ish>`` may use `git rev-parse`_
+  syntax to reference commits relative to the topic ``HEAD``.
+  See additional `backport instructions`_ for details.
+  For example:
+
+  ``Backport: release``
+    Merge the topic branch head into both ``release`` and ``master``.
+  ``Backport: release:HEAD~1^2``
+    Merge the topic branch head's parent's second parent commit into
+    the ``release`` branch.  Merge the topic branch head to ``master``.
+
 * ``Topic-rename: <topic>``: substitute ``<topic>`` for the name of
   the MR topic branch in the constructed merge commit message.
   It is also used in merge commits constructed by ``Do: stage``.
@@ -440,6 +455,8 @@ comment instead):
   rename set in the MR description.
 
 .. _`CMake GitLab Project Masters`: https://gitlab.kitware.com/cmake/cmake/settings/members
+.. _`backport instructions`: https://gitlab.kitware.com/utils/git-workflow/wikis/Backport-topics
+.. _`git rev-parse`: https://git-scm.com/docs/git-rev-parse
 
 Close
 -----