You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
172 lines
4.7 KiB
172 lines
4.7 KiB
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.
|