Commit c26c6949 authored by Brad King's avatar Brad King Committed by Kitware Robot
Browse files

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's avatarKitware Robot <kwrobot@kitware.com>
Merge-request: !925
parents 2d3d88f3 a44d3cc6
......@@ -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
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.
#!/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
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