| 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. |