Help/dev: Add release branch creation to maintainer guide

Help/dev/maint.rst

@@ -7,3 +7,165 @@ See documentation on `CMake Development`_ for more information.
 .. _`CMake Development`: README.rst
 
 .. contents:: Maintainer Processes:
+
+Branch a New Release
+====================
+
+This section covers how to start a new ``release`` branch for a major or
+minor version bump (patch releases remain on their existing branch).
+
+In the following we use the placeholder ``$ver`` to represent the
+version number of the new release with the form ``$major.$minor``,
+and ``$prev`` to represent the version number of the prior release.
+
+Review Prior Release
+--------------------
+
+Review the history around the prior release branch:
+
+.. code-block:: shell
+
+  git log --graph --boundary \
+   ^$(git rev-list --grep="Merge topic 'doc-.*-relnotes'" -n 1 master)~1 \
+   $(git rev-list --grep="Begin post-.* development" -n 1 master) \
+   $(git tag --list *-rc1| tail -1)
+
+Consolidate Release Notes
+-------------------------
+
+Starting from a clean work tree on ``master``, create a topic branch to
+use for consolidating the release notes:
+
+.. code-block:: shell
+
+  git checkout -b doc-$ver-relnotes
+
+Run the `consolidate-relnotes.bash`_ script:
+
+.. code-block:: shell
+
+  Utilities/Release/consolidate-relnotes.bash $ver $prev
+
+.. _`consolidate-relnotes.bash`: ../../Utilities/Release/consolidate-relnotes.bash
+
+This moves notes from the ``Help/release/dev/*.rst`` files into a versioned
+``Help/release/$ver.rst`` file and updates ``Help/release/index.rst`` to
+link to the new document.  Commit the changes with a message such as::
+
+  Help: Consolidate $ver release notes
+
+  Run the `Utilities/Release/consolidate-relnotes.bash` script to move
+  notes from `Help/release/dev/*` into `Help/release/$ver.rst`.
+
+Manually edit ``Help/release/$ver.rst`` to add section headers, organize
+the notes, and revise wording.  Then commit with a message such as::
+
+  Help: Organize and revise $ver release notes
+
+  Add section headers similar to the $prev release notes and move each
+  individual bullet into an appropriate section.  Revise a few bullets.
+
+Open a merge request with the ``doc-$ver-relnotes`` branch for review
+and integration.  Further steps may proceed after this has been merged
+to ``master``.
+
+Update 'release' Branch
+-----------------------
+
+Starting from a clean work tree on ``master``, create a new ``release-$ver``
+branch locally:
+
+.. code-block:: shell
+
+  git checkout -b release-$ver origin/master
+
+Remove the development branch release note infrastructure:
+
+.. code-block:: shell
+
+  git rm Help/release/dev/0-sample-topic.rst
+  sed -i '/^\.\. include:: dev.txt/ {N;d}' Help/release/index.rst
+
+Commit with a message such as::
+
+  Help: Drop development topic notes to prepare release
+
+  Release versions do not have the development topic section of
+  the CMake Release Notes index page.
+
+Update ``Source/CMakeVersion.cmake`` to set the version to
+``$major.$minor.0-rc1``:
+
+.. code-block:: cmake
+
+  # CMake version number components.
+  set(CMake_VERSION_MAJOR $major)
+  set(CMake_VERSION_MINOR $minor)
+  set(CMake_VERSION_PATCH 0)
+  set(CMake_VERSION_RC 1)
+
+Update ``Utilities/Release/upload_release.cmake``:
+
+.. code-block:: cmake
+
+  set(VERSION $ver)
+
+Update uses of ``DEVEL_CMAKE_VERSION`` in the source tree to mention the
+actual version number:
+
+.. code-block:: shell
+
+  $EDITOR $(git grep -l DEVEL_CMAKE_VERSION)
+
+Commit with a message such as::
+
+  CMake $major.$minor.0-rc1 version update
+
+Merge the ``release-$ver`` branch to ``master``:
+
+.. code-block:: shell
+
+  git checkout master
+  git pull
+  git merge --no-ff release-$ver
+
+Begin post-release development by restoring the development branch release
+note infrastructure and the version date from ``origin/master``:
+
+.. code-block:: shell
+
+  git checkout origin/master -- \
+    Source/CMakeVersion.cmake Help/release/dev/0-sample-topic.rst
+  sed -i $'/^Releases/ i\\\n.. include:: dev.txt\\\n' Help/release/index.rst
+
+Update ``Source/CMakeVersion.cmake`` to set the version to
+``$major.$minor.$date``:
+
+.. code-block:: cmake
+
+  # CMake version number components.
+  set(CMake_VERSION_MAJOR $major)
+  set(CMake_VERSION_MINOR $minor)
+  set(CMake_VERSION_PATCH $date)
+  #set(CMake_VERSION_RC 1)
+
+Commit with a message such as::
+
+  Begin post-$ver development
+
+Push the update to the ``master`` and ``release`` branches:
+
+.. code-block:: shell
+
+  git push --atomic origin master release-$ver:release
+
+Announce 'release' Branch
+-------------------------
+
+Send email to the ``[email protected]`` mailing list (perhaps
+in reply to a release preparation thread) announcing that post-release
+development is open::
+
+  I've branched 'release' for $ver.  The repository is now open for
+  post-$ver development.  Please rebase open merge requests on 'master'
+  before staging or merging.