From c913ab61aea87439d6822632a8e74a28a287a460 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 2 Jun 2017 11:46:10 -0400 Subject: Utilities/Release: Add script to consolidate release notes --- Utilities/Release/consolidate-relnotes.bash | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100755 Utilities/Release/consolidate-relnotes.bash 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 ' + +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 -- cgit v0.12 From 4e52809edfbff7565fe19edad5b1c3054f2e2dfe Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 2 Jun 2017 11:13:59 -0400 Subject: Help/dev: Add a CMake Maintainer Guide document Initialize it with placeholder content. This document will serve to contain instructions for CMake maintenance processes. --- Help/dev/README.rst | 9 +++++++++ Help/dev/maint.rst | 9 +++++++++ 2 files changed, 18 insertions(+) create mode 100644 Help/dev/maint.rst 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..c1a2048 --- /dev/null +++ b/Help/dev/maint.rst @@ -0,0 +1,9 @@ +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: -- cgit v0.12 From a44d3cc6ede7d4ef520151fdef5e5cf0a02707b7 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 2 Jun 2017 14:18:41 -0400 Subject: Help/dev: Add release branch creation to maintainer guide --- Help/dev/maint.rst | 162 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 162 insertions(+) diff --git a/Help/dev/maint.rst b/Help/dev/maint.rst index c1a2048..78c06df 100644 --- a/Help/dev/maint.rst +++ b/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 ``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. -- cgit v0.12