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 ...@@ -14,6 +14,11 @@ Review a Merge Request
The `CMake Review Process`_ requires a maintainer to issue the ``Do: merge`` The `CMake Review Process`_ requires a maintainer to issue the ``Do: merge``
command to integrate a merge request. Please check at least the following: 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 * 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), (e.g. it is just ``master`` or the patch changed during review),
add a ``Topic-rename: <topic>`` trailing line to the MR description 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: ...@@ -38,9 +43,10 @@ command to integrate a merge request. Please check at least the following:
of various nightly builders.) of various nightly builders.)
* Ensure that the MR targets the ``master`` branch. A MR intended for * Ensure that the MR targets the ``master`` branch. A MR intended for
the ``release`` branch should be based on ``release`` but still merged the ``release`` branch should be based on ``release`` but still target
to ``master`` first (via ``Do: merge``). A maintainer may then merge ``master``. Use the above-mentioned ``Backport: release`` line to tell
the MR topic to ``release`` manually. ``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 Maintain Current Release
======================== ========================
...@@ -51,6 +57,12 @@ using a local branch named ``release-$ver``, where ``$ver`` is the version ...@@ -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 number of the current release in the form ``$major.$minor``. It is always
merged into ``master`` before publishing. 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 Before merging a ``$topic`` branch into ``release``, verify that the
``$topic`` branch has already been merged to ``master`` via the usual ``$topic`` branch has already been merged to ``master`` via the usual
``Do: merge`` process. Then, to merge the ``$topic`` branch into ``Do: merge`` process. Then, to merge the ``$topic`` branch into
......
...@@ -433,6 +433,21 @@ Additionally, ``Do: merge`` extracts configuration from trailing lines ...@@ -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 in the MR description (the following have no effect if used in a MR
comment instead): 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 * ``Topic-rename: <topic>``: substitute ``<topic>`` for the name of
the MR topic branch in the constructed merge commit message. the MR topic branch in the constructed merge commit message.
It is also used in merge commits constructed by ``Do: stage``. It is also used in merge commits constructed by ``Do: stage``.
...@@ -440,6 +455,8 @@ comment instead): ...@@ -440,6 +455,8 @@ comment instead):
rename set in the MR description. rename set in the MR description.
.. _`CMake GitLab Project Masters`: https://gitlab.kitware.com/cmake/cmake/settings/members .. _`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 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