Commit 75a5d1d4 authored by Brad King's avatar Brad King Committed by Craig Scott

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

parent 12fd957c
......@@ -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
......
......@@ -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
-----
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment