mirror of
https://github.com/Kitware/CMake.git
synced 2026-01-04 12:49:36 -06:00
bd11d78dfc
The previous wording could be misread as ensuring the arguments to the call match the release version. Clarify that one needs to remove the call and replace it with the literal release version string.
370 lines
12 KiB
ReStructuredText
370 lines
12 KiB
ReStructuredText
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:
|
|
|
|
Review a Merge Request
|
|
======================
|
|
|
|
The `CMake Review Process`_ requires a maintainer to issue the ``Do: merge``
|
|
command to integrate a merge request. Please check at least the following:
|
|
|
|
* If the MR source branch (or part of it) should be backported
|
|
to the ``release`` branch (and is already based on a commit
|
|
contained in the ``release`` branch), add a ``Backport: release`` or
|
|
``Backport: release:<commit-ish>`` trailing line to the MR description.
|
|
|
|
* If the MR source branch is not named well for the change it makes
|
|
(e.g. it is just ``master`` or the patch changed during review),
|
|
add a ``Topic-rename: <topic>`` trailing line to the MR description
|
|
to provide a better topic name.
|
|
|
|
* If the MR introduces a new feature or a user-facing behavior change,
|
|
such as a policy, ensure that a ``Help/release/dev/$topic.rst`` file
|
|
is added with a release note.
|
|
|
|
* If a commit changes a specific area, such as a module, its commit
|
|
message should have an ``area:`` prefix on its first line.
|
|
|
|
* If a commit fixes a tracked issue, its commit message should have
|
|
a trailing line such as ``Fixes: #00000``.
|
|
|
|
* Ensure that the MR adds sufficient documentation and test cases.
|
|
|
|
* Ensure that the MR has been tested sufficiently. Typically it should
|
|
be staged for nightly testing with ``Do: stage``. Then manually
|
|
review the `CMake CDash Page`_ to verify that no regressions were
|
|
introduced. (Learn to tolerate spurious failures due to idiosyncrasies
|
|
of various nightly builders.)
|
|
|
|
* Ensure that the MR targets the ``master`` branch. A MR intended for
|
|
the ``release`` branch should be based on ``release`` but still target
|
|
``master``. Use the above-mentioned ``Backport: release`` line to tell
|
|
``Do: merge`` to merge to both. If a MR is merged without the backport
|
|
line, a maintainer may still merge the MR topic to ``release`` manually.
|
|
|
|
Maintain Current Release
|
|
========================
|
|
|
|
The ``release`` branch is used to maintain the current release or release
|
|
candidate. The branch is published with no version number but maintained
|
|
using a local branch named ``release-$ver``, where ``$ver`` is the version
|
|
number of the current release in the form ``$major.$minor``. It is always
|
|
merged into ``master`` before publishing.
|
|
|
|
To merge an open MR to the ``release`` branch, edit its description to
|
|
use the ``Backport: release`` line mentioned above and then ``Do: merge``
|
|
normally. To update the ``release`` branch manually (e.g. to merge a
|
|
``$topic`` branch that was merged without the backport line), use the
|
|
following procedure.
|
|
|
|
Before merging a ``$topic`` branch into ``release``, verify that the
|
|
``$topic`` branch has already been merged to ``master`` via the usual
|
|
``Do: merge`` process. Then, to merge the ``$topic`` branch into
|
|
``release``, start by creating the local branch:
|
|
|
|
.. code-block:: shell
|
|
|
|
git fetch origin
|
|
git checkout -b release-$ver origin/release
|
|
|
|
Merge the ``$topic`` branch into the local ``release-$ver`` branch, making
|
|
sure to include a ``Merge-request: !xxxx`` footer in the commit message:
|
|
|
|
.. code-block:: shell
|
|
|
|
git merge --no-ff $topic
|
|
|
|
Merge the ``release-$ver`` branch to ``master``:
|
|
|
|
.. code-block:: shell
|
|
|
|
git checkout master
|
|
git pull
|
|
git merge --no-ff release-$ver
|
|
|
|
Review new ancestry to ensure nothing unexpected was merged to either branch:
|
|
|
|
.. code-block:: shell
|
|
|
|
git log --graph --boundary origin/master..master
|
|
git log --graph --boundary origin/release..release-$ver
|
|
|
|
Publish both ``master`` and ``release`` simultaneously:
|
|
|
|
.. code-block:: shell
|
|
|
|
git push --atomic origin master release-$ver:release
|
|
|
|
.. _`CMake Review Process`: review.rst
|
|
.. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake
|
|
|
|
Create Release Version
|
|
======================
|
|
|
|
When the ``release`` branch is ready to create a new release, follow the
|
|
steps in the above `Maintain Current Release`_ section to checkout a local
|
|
``release-$ver`` branch, where ``$ver`` is the version number of the
|
|
current release in the form ``$major.$minor``.
|
|
|
|
Edit ``Source/CMakeVersion.cmake`` to set the full version:
|
|
|
|
.. code-block:: cmake
|
|
|
|
# CMake version number components.
|
|
set(CMake_VERSION_MAJOR $major)
|
|
set(CMake_VERSION_MINOR $minor)
|
|
set(CMake_VERSION_PATCH $patch)
|
|
#set(CMake_VERSION_RC $rc) # uncomment for release candidates
|
|
|
|
In the following we use the placeholder ``$fullver`` for the full version
|
|
number of the new release with the form ``$major.$minor.$patch[-rc$rc]``.
|
|
If the version is not a release candidate, comment out the RC version
|
|
component above and leave off the ``-rc$rc`` suffix from ``$fullver``.
|
|
|
|
Commit the release version with the **exact** message ``CMake $fullver``:
|
|
|
|
.. code-block:: shell
|
|
|
|
git commit -m "CMake $fullver"
|
|
|
|
Tag the release using an annotated tag with the same message as the
|
|
commit and named with the **exact** form ``v$fullver``:
|
|
|
|
.. code-block:: shell
|
|
|
|
git tag -s -m "CMake $fullver" "v$fullver"
|
|
|
|
Follow the steps in the above `Maintain Current Release`_ section to
|
|
merge the ``release-$ver`` branch into ``master`` and publish both.
|
|
|
|
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.
|
|
|
|
Update Sphinx ``versionadded`` directives in documents added since
|
|
the previous release by running the `update_versions.py`_ script:
|
|
|
|
.. code-block:: shell
|
|
|
|
Utilities/Sphinx/update_versions.py --since v$prev.0 --overwrite
|
|
|
|
.. _`update_versions.py`: ../../Utilities/Sphinx/update_versions.py
|
|
|
|
Commit the changes with a message such as::
|
|
|
|
Help: Update Sphinx versionadded directives for $ver release
|
|
|
|
Run the script:
|
|
|
|
Utilities/Sphinx/update_versions.py --since v$prev.0 --overwrite
|
|
|
|
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 ``.gitlab-ci.yml`` to drop the upload jobs from the
|
|
packaging pipeline by renaming them to start in ``.``:
|
|
|
|
.. code-block:: shell
|
|
|
|
sed -i 's/^u:/.u:/' .gitlab-ci.yml
|
|
|
|
Commit with a message such as::
|
|
|
|
gitlab-ci: Drop package pipeline upload jobs for release branch
|
|
|
|
The package pipeline for release versions should not upload packages
|
|
automatically to our archive of nightly development versions.
|
|
|
|
Update ``Source/CMakeVersion.cmake`` to set the version to
|
|
``$major.$minor.0-rc0``:
|
|
|
|
.. 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 0)
|
|
|
|
Replace uses of ``DEVEL_CMAKE_VERSION`` in the source tree with
|
|
the literal release version number string ``"$major.$minor.0"``:
|
|
|
|
.. code-block:: shell
|
|
|
|
$EDITOR $(git grep -l DEVEL_CMAKE_VERSION)
|
|
|
|
Commit with a message such as::
|
|
|
|
Begin $ver release versioning
|
|
|
|
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, the nightly package pipeline upload jobs, 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
|
|
sed -i 's/^\.u:/u:/' .gitlab-ci.yml
|
|
|
|
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 0)
|
|
|
|
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
|
|
-------------------------
|
|
|
|
Post a topic to the `CMake Discourse Forum Development Category`_
|
|
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.
|
|
|
|
.. _`CMake Discourse Forum Development Category`: https://discourse.cmake.org/c/development
|
|
|
|
Initial Post-Release Development
|
|
--------------------------------
|
|
|
|
Deprecate policies more than 8 release series old by updating the
|
|
policy range check in ``cmMakefile::SetPolicy``.
|
|
Commit with a message such as::
|
|
|
|
Add deprecation warnings for policies CMP#### and below
|
|
|
|
The OLD behaviors of all policies are deprecated, but only by
|
|
documentation. Add an explicit deprecation diagnostic for policies
|
|
introduced in CMake $OLDVER and below to encourage projects to port
|
|
away from setting policies to OLD.
|
|
|
|
Update the ``cmake_policy`` version range generated by ``install(EXPORT)``
|
|
in ``cmExportFileGenerator::GeneratePolicyHeaderCode`` to end at the
|
|
previous release. We use one release back since we now know all the
|
|
policies added for that version. Commit with a message such as::
|
|
|
|
export: Increase maximum policy version in exported files to $prev
|
|
|
|
The files generatd by `install(EXPORT)` and `export()` commands
|
|
are known to work with policies as of CMake $prev, so enable them
|
|
in sufficiently new CMake versions.
|
|
|
|
Update the ``cmake_minimum_required`` version range in CMake itself:
|
|
|
|
* ``CMakeLists.txt``
|
|
* ``Utilities/Doxygen/CMakeLists.txt``
|
|
* ``Utilities/Sphinx/CMakeLists.txt``
|
|
|
|
to end in the previous release. Commit with a message such as::
|
|
|
|
Configure CMake itself with policies through CMake $prev
|