blob: 889e4e351f39d92a159b74ed1632b432d5d07378 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
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
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
|
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 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.)
.. _`CMake Review Process`: review.rst
.. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake
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.
|
