Merge topic 'doc-dev-maint'

a44d3cc6 Help/dev: Add release branch creation to maintainer guide
4e52809e Help/dev: Add a CMake Maintainer Guide document
c913ab61 Utilities/Release: Add script to consolidate release notes

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !925

3 files changed, 207 insertions, 0 deletions

diff --git a/Help/dev/README.rst b/Help/dev/README.rst
index 163be97..ce62abc 100644
--- a/Help/dev/README.rst
+++ b/Help/dev/README.rst
@@ -38,3 +38,12 @@ CMake developer documentation is provided by the following documents:
 * The `CMake Source Code Guide`_.
 
 .. _`CMake Source Code Guide`: source.rst
+
+Maintainer Documentation
+========================
+
+CMake maintainer documentation is provided by the following documents:
+
+* The `CMake Maintainer Guide`_.
+
+.. _`CMake Maintainer Guide`: maint.rst
diff --git a/Help/dev/maint.rst b/Help/dev/maint.rst
new file mode 100644
index 0000000..78c06df
--- /dev/null
+++ b/Help/dev/maint.rst
@@ -0,0 +1,171 @@
+CMake Maintainer Guide
+**********************
+
+The following is a guide to CMake maintenance processes.
+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 ``cmake-developers@cmake.org`` 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.
diff --git a/Utilities/Release/consolidate-relnotes.bash b/Utilities/Release/consolidate-relnotes.bash
new file mode 100755
index 0000000..91307ac
--- /dev/null
+++ b/Utilities/Release/consolidate-relnotes.bash
@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+
+set -e
+
+usage='usage: consolidate-relnotes.bash <new-release-version> <prev-release-version>'
+
+die() {
+    echo "$@" 1>&2; exit 1
+}
+
+test "$#" = 2 || die "$usage"
+
+files="$(ls Help/release/dev/* | grep -v Help/release/dev/0-sample-topic.rst)"
+title="CMake $1 Release Notes"
+underline="$(echo "$title" | sed 's/./*/g')"
+echo "$title
+$underline
+
+.. only:: html
+
+  .. contents::
+
+Changes made since CMake $2 include the following." > Help/release/"$1".rst
+tail -q -n +3 $files >> Help/release/"$1".rst
+sed -i "/^   $2 / i\\
+   $1 <$1>" Help/release/index.rst
+rm $files