← Back to branch summary

~mmach/netext73/mesa-haswell

« back to all changes in this revision

Viewing changes to docs/releasing.rst

  • Committer: mmach
  • Date: 2022-09-22 19:56:13 UTC
  • Revision ID: netbit73@gmail.com-20220922195613-wtik9mmy20tmor0i
2022-09-22 21:17:09

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/releasing.rst
1
 
Releasing Process
2
 
=================
3
 
 
4
 
Overview
5
 
--------
6
 
 
7
 
This document uses the convention X.Y.Z for the release number with X.Y
8
 
being the stable branch name.
9
 
 
10
 
Mesa provides feature and bugfix releases. Former use zero as patch
11
 
version (Z), while the latter have a non-zero one.
12
 
 
13
 
For example:
14
 
 
15
 
::
16
 
 
17
 
   Mesa 10.1.0 - 10.1 branch, feature
18
 
   Mesa 10.1.4 - 10.1 branch, bugfix
19
 
   Mesa 12.0.0 - 12.0 branch, feature
20
 
   Mesa 12.0.2 - 12.0 branch, bugfix
21
 
 
22
 
.. _schedule:
23
 
 
24
 
Release schedule
25
 
----------------
26
 
 
27
 
Releases should happen on Wednesdays. Delays can occur although those
28
 
should be kept to a minimum.
29
 
 
30
 
See our :doc:`calendar <release-calendar>` for information about how
31
 
the release schedule is planned, and the date and other details for
32
 
individual releases.
33
 
 
34
 
Feature releases
35
 
----------------
36
 
 
37
 
-  Available approximately every three months.
38
 
-  Feature releases are branched on or around the second Wednesday of
39
 
   January, April, July, and October.
40
 
-  Initial time plan available 2-4 weeks before the planned branchpoint
41
 
   (rc1) on the mesa-announce@ mailing list.
42
 
-  Typically, the final release will happen after 4 candidates.
43
 
   Additional ones may be needed in order to resolve blocking
44
 
   regressions, though.
45
 
 
46
 
Stable releases
47
 
---------------
48
 
 
49
 
-  Normally available once every two weeks.
50
 
-  Only the latest branch has releases. See note below.
51
 
 
52
 
.. note::
53
 
 
54
 
   There is one or two releases overlap when changing branches. For
55
 
   example:
56
 
 
57
 
   The final release from the 12.0 series Mesa 12.0.5 will be out around
58
 
   the same time (or shortly after) 13.0.1 is out.
59
 
 
60
 
   This also involves that, as a final release may be delayed due to the
61
 
   need of additional candidates to solve some blocking regression(s), the
62
 
   release manager might have to update the
63
 
   :doc:`calendar <release-calendar>` with additional bug fix releases of
64
 
   the current stable branch.
65
 
 
66
 
.. _pickntest:
67
 
 
68
 
Cherry-picking and testing
69
 
--------------------------
70
 
 
71
 
Commits nominated for the active branch are picked as based on the
72
 
:ref:`criteria <criteria>` as described in the same
73
 
section.
74
 
 
75
 
Nominations happen via special tags in the commit messages, and via
76
 
GitLab merge requests against the staging branches. There are special
77
 
scripts used to read the tags.
78
 
 
79
 
The maintainer should watch or be in contact with the Intel CI team, as
80
 
well as watch the GitLab CI for regressions.
81
 
 
82
 
Cherry picking should be done with the '-x' switch (to automatically add
83
 
"cherry picked from ..." to the commit message):
84
 
 
85
 
``git cherry-pick -x abcdef12345667890``
86
 
 
87
 
Developers can request, *as an exception*, patches to be applied up-to
88
 
the last one hour before the actual release. This is made **only** with
89
 
explicit permission/request, and the patch **must** be very well
90
 
contained. Thus it cannot affect more than one driver/subsystem.
91
 
 
92
 
Following developers have requested permanent exception
93
 
 
94
 
-  *Ilia Mirkin*
95
 
-  *AMD team*
96
 
 
97
 
The GitLab CI must pass.
98
 
 
99
 
For Windows related changes, the main contact point is Brian Paul. Jose
100
 
Fonseca can also help as a fallback contact.
101
 
 
102
 
For Android related changes, the main contact is Tapani Pälli. Mauro
103
 
Rossi is collaborating with Android-x86 and may provide feedback about
104
 
the build status in that project.
105
 
 
106
 
For MacOSX related changes, Jeremy Huddleston Sequoia is currently a
107
 
good contact point.
108
 
 
109
 
.. note::
110
 
 
111
 
   If a patch in the current queue needs any additional fix(es),
112
 
   then they should be squashed together. The commit messages and the
113
 
   "``cherry picked from``"-tags must be preserved.
114
 
 
115
 
   .. code-block:: console
116
 
 
117
 
      git show b10859ec41d09c57663a258f43fe57c12332698e
118
 
 
119
 
      commit b10859ec41d09c57663a258f43fe57c12332698e
120
 
      Author: Jonas Pfeil <pfeiljonas@gmx.de>
121
 
      Date:   Wed Mar 1 18:11:10 2017 +0100
122
 
 
123
 
         ralloc: Make sure ralloc() allocations match malloc()'s alignment.
124
 
 
125
 
         The header of ralloc needs to be aligned, because the compiler assumes
126
 
         ...
127
 
 
128
 
         (cherry picked from commit cd2b55e536dc806f9358f71db438dd9c246cdb14)
129
 
 
130
 
         Squashed with commit:
131
 
 
132
 
         ralloc: don't leave out the alignment factor
133
 
 
134
 
         Experimentation shows that without alignment factor GCC and Clang choose
135
 
         ...
136
 
 
137
 
         (cherry picked from commit ff494fe999510ea40e3ed5827e7818550b6de126)
138
 
 
139
 
Regression/functionality testing
140
 
--------------------------------
141
 
 
142
 
-  *no regressions should be observed for Piglit/dEQP/CTS/Vulkan on
143
 
   Intel platforms*
144
 
-  *no regressions should be observed for Piglit using the swrast,
145
 
   softpipe and llvmpipe drivers*
146
 
 
147
 
.. _stagingbranch:
148
 
 
149
 
Staging branch
150
 
--------------
151
 
 
152
 
A live branch, which contains the currently merge/rejected patches is
153
 
available in the main repository under ``staging/X.Y``. For example:
154
 
 
155
 
::
156
 
 
157
 
   staging/18.1 - WIP branch for the 18.1 series
158
 
   staging/18.2 - WIP branch for the 18.2 series
159
 
 
160
 
Notes:
161
 
 
162
 
-  People are encouraged to test the staging branch and report
163
 
   regressions.
164
 
-  The branch history is not stable and it **will** be rebased,
165
 
 
166
 
Making a branchpoint
167
 
--------------------
168
 
 
169
 
A branchpoint is made such that new development can continue in parallel
170
 
to stabilization and bugfixing.
171
 
 
172
 
.. note::
173
 
 
174
 
   Before doing a branch ensure that basic build and ``meson test``
175
 
   testing is done and there are little to-no issues. Ideally all of those
176
 
   should be tackled already.
177
 
 
178
 
To setup the branchpoint:
179
 
 
180
 
.. code-block:: console
181
 
 
182
 
   git fetch origin # make sure we have the latest commits
183
 
   git checkout main # make sure we're on main
184
 
   git reset origin # make sure we're at the latest commit
185
 
 
186
 
   git tag -s X.Y-branchpoint -m "Mesa X.Y branchpoint"
187
 
 
188
 
   # Make sure main can carry on at the new version
189
 
   $EDITOR VERSION # bump the version number, keeping in mind the wrap around at the end of the year
190
 
   git commit -asm 'VERSION: bump to X.(Y+1)'
191
 
   truncate -s0 docs/relnotes/new_features.txt
192
 
   git commit -asm 'docs: reset new_features.txt'
193
 
   git push origin main
194
 
 
195
 
   # Create the tag and branches on the server
196
 
   git push origin X.Y-branchpoint
197
 
   git push origin X.Y-branchpoint:refs/heads/X.Y
198
 
   git push origin X.Y-branchpoint:refs/heads/staging/X.Y
199
 
 
200
 
Now go to
201
 
`GitLab <https://gitlab.freedesktop.org/mesa/mesa/-/milestones>`__ and
202
 
add the new Mesa version X.Y.
203
 
 
204
 
Check that there are no distribution breaking changes and revert them if
205
 
needed. For example: files being overwritten on install, etc. Happens
206
 
extremely rarely - we had only one case so far (see commit
207
 
2ced8eb136528914e1bf4e000dea06a9d53c7e04).
208
 
 
209
 
Making a new release
210
 
--------------------
211
 
 
212
 
These are the instructions for making a new Mesa release.
213
 
 
214
 
Get latest source files
215
 
~~~~~~~~~~~~~~~~~~~~~~~
216
 
 
217
 
Ensure the latest code is available - both in your local main and the
218
 
relevant branch.
219
 
 
220
 
Perform basic testing
221
 
~~~~~~~~~~~~~~~~~~~~~
222
 
 
223
 
Most of the testing should already be done during the
224
 
:ref:`cherry-pick <pickntest>` So we do a quick 'touch test'
225
 
 
226
 
-  meson dist
227
 
-  the produced binaries work
228
 
 
229
 
Here is one solution:
230
 
 
231
 
.. code-block:: console
232
 
 
233
 
   __glxgears_cmd='glxgears 2>&1 | grep -v "configuration file"'
234
 
   __es2info_cmd='es2_info 2>&1 | egrep "GL_VERSION|GL_RENDERER|.*dri\.so"'
235
 
   __es2gears_cmd='es2gears_x11 2>&1 | grep -v "configuration file"'
236
 
   test "x$LD_LIBRARY_PATH" != 'x' && __old_ld="$LD_LIBRARY_PATH"
237
 
   export LD_LIBRARY_PATH=`pwd`/test/usr/local/lib/:"${__old_ld}"
238
 
   export LIBGL_DRIVERS_PATH=`pwd`/test/usr/local/lib/dri/
239
 
   export LIBGL_DEBUG=verbose
240
 
   eval $__glxinfo_cmd
241
 
   eval $__glxgears_cmd
242
 
   eval $__es2info_cmd
243
 
   eval $__es2gears_cmd
244
 
   export LIBGL_ALWAYS_SOFTWARE=true
245
 
   eval $__glxinfo_cmd
246
 
   eval $__glxgears_cmd
247
 
   eval $__es2info_cmd
248
 
   eval $__es2gears_cmd
249
 
   export LIBGL_ALWAYS_SOFTWARE=true
250
 
   export GALLIUM_DRIVER=softpipe
251
 
   eval $__glxinfo_cmd
252
 
   eval $__glxgears_cmd
253
 
   eval $__es2info_cmd
254
 
   eval $__es2gears_cmd
255
 
   # Smoke test DOTA2
256
 
   unset LD_LIBRARY_PATH
257
 
   test "x$__old_ld" != 'x' && export LD_LIBRARY_PATH="$__old_ld" && unset __old_ld
258
 
   unset LIBGL_DRIVERS_PATH
259
 
   unset LIBGL_DEBUG
260
 
   unset LIBGL_ALWAYS_SOFTWARE
261
 
   unset GALLIUM_DRIVER
262
 
   export VK_ICD_FILENAMES=`pwd`/test/usr/local/share/vulkan/icd.d/intel_icd.x86_64.json
263
 
   steam steam://rungameid/570  -vconsole -vulkan
264
 
   unset VK_ICD_FILENAMES
265
 
 
266
 
Create release notes for the new release
267
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
268
 
 
269
 
The release notes are completely generated by the
270
 
``bin/gen_release_notes.py`` script. Simply run this script **before**
271
 
bumping the version. You'll need to come back to this file once the
272
 
tarball is generated to add its ``sha256sum``.
273
 
 
274
 
Increment the version contained in the file ``VERSION`` at Mesa's top-level,
275
 
then commit this change and **push the branch** (if you forget to do
276
 
this, ``release.sh`` below will fail).
277
 
 
278
 
Use the release.sh script from xorg `util-modular <https://gitlab.freedesktop.org/xorg/util/modular>`__
279
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
280
 
 
281
 
Start the release process.
282
 
 
283
 
.. code-block:: console
284
 
 
285
 
   ../relative/path/to/release.sh . # append --dist if you've already done distcheck above
286
 
 
287
 
Pay close attention to the prompts as you might be required to enter
288
 
your GPG and SSH passphrase(s) to sign and upload the files,
289
 
respectively.
290
 
 
291
 
Ensure that you do sign the tarballs, that your key is mentioned in the
292
 
release notes, and is published in `release-maintainers-keys.asc
293
 
<release-maintainers-keys.asc>`__.
294
 
 
295
 
 
296
 
Add the sha256sums to the release notes
297
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
298
 
 
299
 
Edit ``docs/relnotes/X.Y.Z.rst`` to add the ``sha256sum`` as available in the
300
 
``mesa-X.Y.Z.announce`` template. Commit this change.
301
 
 
302
 
Don't forget to push the commits to both the ``staging/X.Y`` branch and
303
 
the ``X.Y`` branch:
304
 
 
305
 
.. code-block:: console
306
 
 
307
 
   git push origin HEAD:staging/X.Y
308
 
   git push origin HEAD:X.Y
309
 
 
310
 
 
311
 
Back on mesa main, add the new release notes into the tree
312
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
313
 
 
314
 
Something like the following steps will do the trick:
315
 
 
316
 
.. code-block:: console
317
 
 
318
 
   git cherry-pick -x X.Y~1
319
 
   git cherry-pick -x X.Y
320
 
 
321
 
Then run the
322
 
 
323
 
.. code-block:: console
324
 
 
325
 
   ./bin/post_version.py X.Y.Z
326
 
 
327
 
, where X.Y.Z is the version you just made. This will update
328
 
docs/relnotes.rst and docs/release-calendar.csv. It will then generate
329
 
a Git commit automatically. Check that everything looks correct and
330
 
push:
331
 
 
332
 
.. code-block:: console
333
 
 
334
 
      git push origin main X.Y
335
 
 
336
 
Announce the release
337
 
--------------------
338
 
 
339
 
Use the generated template during the releasing process.
340
 
 
341
 
Again, pay attention to add a note to warn about a final release in a
342
 
series, if that is the case.
343
 
 
344
 
Update GitLab issues
345
 
--------------------
346
 
 
347
 
Parse through the bug reports as listed in the docs/relnotes/X.Y.Z.rst
348
 
document. If there's outstanding action, close the bug referencing the
349
 
commit ID which addresses the bug and mention the Mesa version that has
350
 
the fix.
351
 
 
352
 
.. note: the above is not applicable to all the reports, so use common sense.