maint.rst 9.63 KB
Newer Older
1 2 3 4 5 6 7 8 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:
10

11 12 13 14 15 16
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:

17 18 19 20 21
* 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.

22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
* 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``.

37 38
* Ensure that the MR adds sufficient documentation and test cases.

39 40 41 42 43 44
* 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.)

45
* Ensure that the MR targets the ``master`` branch.  A MR intended for
46 47 48 49
  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.
50 51 52 53 54 55 56 57 58 59

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.

60 61 62 63 64 65
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.

66 67 68 69
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:
70 71 72 73 74 75

.. code-block:: shell

  git fetch origin
  git checkout -b release-$ver origin/release

76 77
Merge the ``$topic`` branch into the local ``release-$ver`` branch, making
sure to include a ``Merge-request: !xxxx`` footer in the commit message:
78 79 80 81 82 83 84 85 86 87 88 89 90

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

91 92 93 94 95 96 97
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

98 99 100 101 102 103
Publish both ``master`` and ``release`` simultaneously:

.. code-block:: shell

  git push --atomic origin master release-$ver:release

104 105 106
.. _`CMake Review Process`: review.rst
.. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake

107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145
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.

146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231
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
232
``$major.$minor.0-rc0``:
233 234 235 236 237 238 239

.. code-block:: cmake

  # CMake version number components.
  set(CMake_VERSION_MAJOR $major)
  set(CMake_VERSION_MINOR $minor)
  set(CMake_VERSION_PATCH 0)
240
  set(CMake_VERSION_RC 0)
241 242 243 244 245 246 247 248 249 250

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

251
  Begin $ver release versioning
252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270

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
271
``$major.$minor.$date``:
272 273 274 275 276 277 278

.. code-block:: cmake

  # CMake version number components.
  set(CMake_VERSION_MAJOR $major)
  set(CMake_VERSION_MINOR $minor)
  set(CMake_VERSION_PATCH $date)
279
  #set(CMake_VERSION_RC 0)
280 281 282 283 284 285 286 287 288 289 290 291 292 293

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

294 295
Post a topic to the `CMake Discourse Forum Development Category`_
announcing that post-release development is open::
296

297 298
  I've branched `release` for $ver.  The repository is now open for
  post-$ver development.  Please rebase open merge requests on `master`
299
  before staging or merging.
300 301

.. _`CMake Discourse Forum Development Category`: https://discourse.cmake.org/c/development