docs: add release notes for 17.1.7
[mesa.git] / docs / releasing.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <html lang="en">
3 <head>
4 <meta http-equiv="content-type" content="text/html; charset=utf-8">
5 <title>Releasing process</title>
6 <link rel="stylesheet" type="text/css" href="mesa.css">
7 </head>
8 <body>
9
10 <div class="header">
11 <h1>The Mesa 3D Graphics Library</h1>
12 </div>
13
14 <iframe src="contents.html"></iframe>
15 <div class="content">
16
17
18 <h1>Releasing process</h1>
19
20 <ul>
21 <li><a href="#overview">Overview</a>
22 <li><a href="#schedule">Release schedule</a>
23 <li><a href="#pickntest">Cherry-pick and test</a>
24 <li><a href="#branch">Making a branchpoint</a>
25 <li><a href="#prerelease">Pre-release announcement</a>
26 <li><a href="#release">Making a new release</a>
27 <li><a href="#announce">Announce the release</a>
28 <li><a href="#website">Update the mesa3d.org website</a>
29 <li><a href="#bugzilla">Update Bugzilla</a>
30 </ul>
31
32
33 <h1 id="overview">Overview</h1>
34
35 <p>
36 This document uses the convention X.Y.Z for the release number with X.Y being
37 the stable branch name.
38 <br>
39 Mesa provides feature and bugfix releases. Former use zero as patch version (Z),
40 while the latter have a non-zero one.
41 </p>
42
43 <p>
44 For example:
45 </p>
46 <pre>
47 Mesa 10.1.0 - 10.1 branch, feature
48 Mesa 10.1.4 - 10.1 branch, bugfix
49 Mesa 12.0.0 - 12.0 branch, feature
50 Mesa 12.0.2 - 12.0 branch, bugfix
51 </pre>
52
53
54 <h1 id="schedule">Release schedule</h1>
55
56 <p>
57 Releases should happen on Fridays. Delays can occur although those should be keep
58 to a minimum.
59 <br>
60 See our <a href="release-calendar.html" target="_parent">calendar</a> for the
61 date and other details for individual releases.
62 </p>
63
64 <h2>Feature releases</h2>
65 <ul>
66 <li>Available approximately every three months.
67 <li>Initial timeplan available 2-4 weeks before the planned branchpoint (rc1)
68 on the mesa-announce@ mailing list.
69 <li>A <a href="#prerelease">pre-release</a> announcement should be available
70 approximately 24 hours before the final (non-rc) release.
71 </ul>
72
73 <h2>Stable releases</h2>
74 <ul>
75 <li>Normally available once every two weeks.
76 <li>Only the latest branch has releases. See note below.
77 <li>A <a href="#prerelease">pre-release</a> announcement should be available
78 approximately 48 hours before the actual release.
79 </ul>
80
81 <p>
82 Note: There is one or two releases overlap when changing branches. For example:
83 <br>
84 The final release from the 12.0 series Mesa 12.0.5 will be out around the same
85 time (or shortly after) 13.0.1 is out.
86 </p>
87
88
89 <h1 id="pickntest">Cherry-picking and testing</h1>
90
91 <p>
92 Commits nominated for the active branch are picked as based on the
93 <a href="submittingpatches.html#criteria" target="_parent">criteria</a> as
94 described in the same section.
95 </p>
96
97 <p>
98 Nomination happens in the mesa-stable@ mailing list. However,
99 maintainer is resposible of checking for forgotten candidates in the
100 master branch. This is achieved by a combination of ad-hoc scripts and
101 a casual search for terms such as regression, fix, broken and similar.
102 </p>
103
104 <p>
105 Maintainer is also responsible for testing in various possible permutations of
106 the autoconf and scons build.
107 </p>
108
109 <h2>Cherry-picking and build/check testing</h2>
110
111 <p>Done continuously up-to the <a href="#prerelease">pre-release</a> announcement.</p>
112
113 <p>
114 As an exception, patches can be applied up-to the last ~1h before the actual
115 release. This is made <strong>only</strong> with explicit permission/request,
116 and the patch <strong>must</strong> be very well contained. Thus it cannot
117 affect more than one driver/subsystem.
118 </p>
119
120 <p>
121 Currently Ilia Mirkin and AMD devs have requested "permanent" exception.
122 </p>
123
124 <ul>
125 <li>make distcheck, scons and scons check must pass
126 <li>Testing with different version of system components - LLVM and others is also
127 performed where possible.
128 <li>As a general rule, testing with various combinations of configure
129 switches, depending on the specific patchset.
130 </ul>
131
132 <p>
133 Achieved by combination of local ad-hoc scripts, mingw-w64 cross
134 compilation and AppVeyor plus Travis-CI, the latter as part of their
135 Github integration.
136 </p>
137
138 <p>
139 For Windows related changes, the main contact point is Brian
140 Paul. Jose Fonseca can also help as a fallback contact.
141 </p>
142
143 <p>
144 For Android related changes, the main contact is Tapani
145 P&auml;lli. Mauro Rossi is collaborating with android-x86 and may
146 provide feedback about the build status in that project.
147 </p>
148
149 <p>
150 For MacOSX related changes, Jeremy Huddleston Sequoia is currently a
151 good contact point.
152 </p>
153
154 <p>
155 <strong>Note:</strong> If a patch in the current queue needs any additional
156 fix(es), then they should be squashed together.
157 <br>
158 The commit messages and the <code>cherry picked from</code> tags must be preserved.
159 </p>
160
161 <p>
162 This should be noted in the <a href="#prerelease">pre-announce</a> email.
163 </p>
164
165 <pre>
166 git show b10859ec41d09c57663a258f43fe57c12332698e
167
168 commit b10859ec41d09c57663a258f43fe57c12332698e
169 Author: Jonas Pfeil &lt;pfeiljonas@gmx.de&gt;
170 Date: Wed Mar 1 18:11:10 2017 +0100
171
172 ralloc: Make sure ralloc() allocations match malloc()'s alignment.
173
174 The header of ralloc needs to be aligned, because the compiler assumes
175 ...
176
177 (cherry picked from commit cd2b55e536dc806f9358f71db438dd9c246cdb14)
178
179 Squashed with commit:
180
181 ralloc: don't leave out the alignment factor
182
183 Experimentation shows that without alignment factor gcc and clang choose
184 ...
185
186 (cherry picked from commit ff494fe999510ea40e3ed5827e7818550b6de126)
187 </pre>
188
189 <h2>Regression/functionality testing</h2>
190
191 <p>
192 Less often (once or twice), shortly before the pre-release announcement.
193 Ensure that testing is redone if Intel devs have requested an exception, as per above.
194 </p>
195
196 <ul>
197 <li><em>no regressions should be observed for Piglit/dEQP/CTS/Vulkan on Intel platforms</em>
198 <li><em>no regressions should be observed for Piglit using the swrast, softpipe
199 and llvmpipe drivers</em>
200 </ul>
201
202 <p>
203 Currently testing is performed courtesy of the Intel OTC team and their Jenkins CI setup. Check with the Intel team over IRC how to get things setup.
204 </p>
205
206 <p>
207 Installing the built driver from the pre-announced RC branch in the
208 system and making some every day's use until the release may be a good
209 idea too.
210 </p>
211
212
213 <h1 id="branch">Making a branchpoint</h1>
214
215 <p>
216 A branchpoint is made such that new development can continue in parallel to
217 stabilisation and bugfixing.
218 </p>
219
220 <p>
221 Note: Before doing a branch ensure that basic build and <code>make check</code>
222 testing is done and there are little to-no issues.
223 <br>
224 Ideally all of those should be tackled already.
225 </p>
226
227 <p>
228 Check if the version number is going to remain as, alternatively
229 <code> git mv docs/relnotes/{current,new}.html </code> as appropriate.
230 </p>
231
232 <p>
233 To setup the branchpoint:
234 </p>
235 <pre>
236 git checkout master # make sure we're in master first
237 git tag -s X.Y-branchpoint -m "Mesa X.Y branchpoint"
238 git checkout -b X.Y
239 git checkout master
240 $EDITOR VERSION # bump the version number
241 git commit -as
242 cp docs/relnotes/{X.Y,X.Y+1}.html # copy/create relnotes template
243 git commit -as
244 git push origin X.Y-branchpoint X.Y
245 </pre>
246
247 <p>
248 Now go to
249 <a href="https://bugs.freedesktop.org/editversions.cgi?action=add&amp;product=Mesa" target="_parent">Bugzilla</a> and add the new Mesa version X.Y.
250 </p>
251
252 <p>
253 Check that there are no distribution breaking changes and revert them if needed.
254 For example: files being overwritten on install, etc. Happens extremely rarely -
255 we had only one case so far (see commit 2ced8eb136528914e1bf4e000dea06a9d53c7e04).
256 </p>
257
258 <p>
259 Proceed to <a href="#release">release</a> -rc1.
260 </p>
261
262
263 <h1 id="prerelease">Pre-release announcement</h1>
264
265 <p>
266 It comes shortly after outstanding patches in the respective branch are pushed.
267 Developers can check, in brief, what's the status of their patches. They,
268 alongside very early testers, are strongly encouraged to test the branch and
269 report any regressions.
270 <br>
271 It is followed by a brief period (normally 24 or 48 hours) before the actual
272 release is made.
273 </p>
274
275 <h2>Terminology used</h2>
276
277 <ul><li>Nominated</ul>
278
279 <p>
280 Patch that is nominated but yet to to merged in the patch queue/branch.
281 </p>
282
283 <ul><li>Queued</ul>
284
285 <p>
286 Patch is in the queue/branch and will feature in the next release.
287 Barring reported regressions or objections from developers.
288 </p>
289
290 <ul><li>Rejected</ul>
291
292 <p>
293 Patch does not fit the
294 <a href="submittingpatches.html#criteria" target="_parent">criteria</a> and
295 is followed by a brief information.
296 <br>
297 The release maintainer is human so if you believe you've spotted a mistake do
298 let them know.
299 </p>
300
301 <h2>Format/template</h2>
302 <pre>
303 Subject: [ANNOUNCE] Mesa X.Y.Z release candidate
304 To: mesa-announce@...
305 Cc: mesa-dev@...
306
307 Hello list,
308
309 The candidate for the Mesa X.Y.Z is now available. Currently we have:
310 - NUMBER queued
311 - NUMBER nominated (outstanding)
312 - and NUMBER rejected patches
313
314 BRIEF SUMMARY OF CHANGES
315
316 Take a look at section "Mesa stable queue" for more information.
317
318
319 Testing reports/general approval
320 --------------------------------
321 Any testing reports (or general approval of the state of the branch) will be
322 greatly appreciated.
323
324 The plan is to have X.Y.Z this DAY (DATE), around or shortly after TIME.
325
326 If you have any questions or suggestions - be that about the current patch
327 queue or otherwise, please go ahead.
328
329
330 Trivial merge conflicts
331 -----------------------
332 List of commits where manual intervention was required.
333 Keep the authors in the CC list.
334
335 commit SHA
336 Author: AUTHOR
337
338 COMMIT SUMMARY
339
340 CHERRY PICKED FROM
341
342
343 For example:
344
345 commit 990f395e007c3204639daa34efc3049f350ee819
346 Author: Emil Velikov &lt;emil.velikov@collabora.com&gt;
347
348 anv: automake: cleanup the generated json file during make clean
349
350 (cherry picked from commit 8df581520a823564be0ab5af7dbb7d501b1c9670)
351
352
353 Cheers,
354 Emil
355
356
357 Mesa stable queue
358 -----------------
359
360 Nominated (NUMBER)
361 ==================
362
363 AUTHOR (NUMBER):
364 SHA COMMIT SUMMARY
365
366 For example:
367
368 Dave Airlie (1):
369 2de85eb radv: fix texturesamples to handle single sample case
370
371
372 Queued (NUMBER)
373 ===============
374
375 AUTHOR (NUMBER):
376 COMMIT SUMMARY
377
378 For example:
379
380 Jonas Pfeil (1):
381 ralloc: Make sure ralloc() allocations match malloc()'s alignment.
382 Squashed with
383 ralloc: don't leave out the alignment factor
384
385 Rejected (NUMBER)
386 =================
387
388 Rejected (11)
389 =============
390
391 AUTHOR (NUMBER):
392 SHA COMMIT SUMMARY
393
394 Reason: ...
395 </pre>
396
397
398 <h1 id="release">Making a new release</h1>
399
400 <p>
401 These are the instructions for making a new Mesa release.
402 </p>
403
404 <h3>Get latest source files</h3>
405
406 <p>
407 Ensure the latest code is available - both in your local master and the
408 relevant branch.
409 </p>
410
411 <h3>Perform basic testing</h3>
412
413 <p>
414 Most of the testing should already be done during the
415 <a href="#pickntest">cherry-pick</a> and
416 <a href="#prerelease">pre-announce</a> stages.
417 So we do a quick 'touch test'
418 </p>
419
420 <ul>
421 <li>make distcheck (you can omit this if you're not using --dist below)
422 <li>scons (from release tarball)
423 <li>the produced binaries work
424 </ul>
425
426 <p>
427 Here is one solution that I've been using.
428 </p>
429
430 <pre>
431 git clean -fXd; git clean -nxd
432 read # quick cross check any outstanding files
433 export __version=`cat VERSION`
434 export __mesa_root=../
435 export __build_root=./foo
436 chmod 755 -fR $__build_root; rm -rf $__build_root
437 mkdir -p $__build_root &amp;&amp; cd $__build_root
438
439 # For the distcheck, you may want to specify which LLVM to use:
440 # export LLVM_CONFIG=/usr/lib/llvm-3.9/bin/llvm-config
441 $__mesa_root/autogen.sh &amp;&amp; make -j2 distcheck
442
443 # Build check the tarballs (scons, linux)
444 tar -xaf mesa-$__version.tar.xz &amp;&amp; cd mesa-$__version
445 scons
446 cd .. &amp;&amp; rm -rf mesa-$__version
447
448 # Build check the tarballs (scons, windows/mingw)
449 # You may need to unset LLVM if you set it before:
450 # unset LLVM_CONFIG
451 tar -xaf mesa-$__version.tar.xz &amp;&amp; cd mesa-$__version
452 scons platform=windows toolchain=crossmingw
453 cd .. &amp;&amp; rm -rf mesa-$__version
454
455 # Test the automake binaries
456 tar -xaf mesa-$__version.tar.xz &amp;&amp; cd mesa-$__version
457 # You may want to specify which LLVM to use:
458 ./configure \
459 --with-dri-drivers=i965,swrast \
460 --with-gallium-drivers=swrast \
461 --with-vulkan-drivers=intel \
462 --enable-llvm-shared-libs \
463 --enable-llvm \
464 --with-llvm-prefix=/usr/lib/llvm-3.9 \
465 --enable-glx-tls \
466 --enable-gbm \
467 --enable-egl \
468 --with-platforms=x11,drm,wayland,surfaceless
469 make -j2 &amp;&amp; DESTDIR=`pwd`/test make -j6 install
470 __glxinfo_cmd='glxinfo 2>&amp;1 | egrep -o "Mesa.*|Gallium.*|.*dri\.so"'
471 __glxgears_cmd='glxgears 2>&amp;1 | grep -v "configuration file"'
472 __es2info_cmd='es2_info 2>&amp;1 | egrep "GL_VERSION|GL_RENDERER|.*dri\.so"'
473 __es2gears_cmd='es2gears_x11 2>&amp;1 | grep -v "configuration file"'
474 test "x$LD_LIBRARY_PATH" != 'x' &amp;&amp; __old_ld="$LD_LIBRARY_PATH"
475 export LD_LIBRARY_PATH=`pwd`/test/usr/local/lib/:"${__old_ld}"
476 export LIBGL_DRIVERS_PATH=`pwd`/test/usr/local/lib/dri/
477 export LIBGL_DEBUG=verbose
478 eval $__glxinfo_cmd
479 eval $__glxgears_cmd
480 eval $__es2info_cmd
481 eval $__es2gears_cmd
482 export LIBGL_ALWAYS_SOFTWARE=1
483 eval $__glxinfo_cmd
484 eval $__glxgears_cmd
485 eval $__es2info_cmd
486 eval $__es2gears_cmd
487 export LIBGL_ALWAYS_SOFTWARE=1
488 export GALLIUM_DRIVER=softpipe
489 eval $__glxinfo_cmd
490 eval $__glxgears_cmd
491 eval $__es2info_cmd
492 eval $__es2gears_cmd
493 # Smoke test DOTA2
494 unset LD_LIBRARY_PATH
495 test "x$__old_ld" != 'x' &amp;&amp; export LD_LIBRARY_PATH="$__old_ld" &amp;&amp; unset __old_ld
496 unset LIBGL_DRIVERS_PATH
497 unset LIBGL_DEBUG
498 unset LIBGL_ALWAYS_SOFTWARE
499 export VK_ICD_FILENAMES=`pwd`/src/intel/vulkan/dev_icd.json
500 steam steam://rungameid/570 -vconsole -vulkan
501 </pre>
502
503 <h3>Update version in file VERSION</h3>
504
505 <p>
506 Increment the version contained in the file VERSION at Mesa's top-level, then
507 commit this change.
508 </p>
509
510 <h3>Create release notes for the new release</h3>
511
512 <p>
513 Create a new file docs/relnotes/X.Y.Z.html, (follow the style of the previous
514 release notes). Note that the sha256sums section of the release notes should
515 be empty (TBD) at this point.
516 </p>
517
518 <p>
519 Two scripts are available to help generate portions of the release notes:
520 </p>
521
522 <pre>
523 ./bin/bugzilla_mesa.sh
524 ./bin/shortlog_mesa.sh
525 </pre>
526
527 <p>
528 The first script identifies commits that reference bugzilla bugs and obtains
529 the descriptions of those bugs from bugzilla. The second script generates a
530 log of all commits. In both cases, HTML-formatted lists are printed to stdout
531 to be included in the release notes.
532 </p>
533
534 <p>
535 Commit these changes and push the branch.
536 </p>
537
538 <pre>
539 git push origin HEAD
540 </pre>
541
542
543 <h3>Use the release.sh script from xorg <a href="https://cgit.freedesktop.org/xorg/util/modular/">util-modular</a></h3>
544
545 <p>
546 Start the release process.
547 </p>
548
549 <pre>
550 # For the dist/distcheck, you may want to specify which LLVM to use:
551 # export LLVM_CONFIG=/usr/lib/llvm-3.9/bin/llvm-config
552 ../relative/path/to/release.sh . # append --dist if you've already done distcheck above
553 </pre>
554
555 <p>
556 Pay close attention to the prompts as you might be required to enter your GPG
557 and SSH passphrase(s) to sign and upload the files, respectively.
558 </p>
559
560 <h3>Add the sha256sums to the release notes</h3>
561
562 <p>
563 Edit docs/relnotes/X.Y.Z.html to add the sha256sums as available in the mesa-X.Y.Z.announce template. Commit this change.
564 </p>
565
566 <h3>Back on mesa master, add the new release notes into the tree</h3>
567
568 <p>
569 Something like the following steps will do the trick:
570 </p>
571
572 <pre>
573 git cherry-pick -x X.Y~1
574 git cherry-pick -x X.Y
575 </pre>
576
577 <p>
578 Also, edit docs/relnotes.html to add a link to the new release notes,
579 edit docs/index.html to add a news entry, and remove the version from
580 docs/release-calendar.html. Then commit and push:
581 </p>
582
583 <pre>
584 git commit -as -m "docs: update calendar, add news item and link release notes for X.Y.Z"
585 git push origin master X.Y
586 </pre>
587
588
589 <h1 id="announce">Announce the release</h1>
590
591 <p>
592 Use the generated template during the releasing process.
593 </p>
594
595
596 <h1 id="website">Update the mesa3d.org website</h1>
597
598 <p>
599 As the hosting was moved to freedesktop, git hooks are deployed to update the
600 website. Manually check that it is updated 5-10 minutes after the final <code>git push</code>
601 </p>
602
603
604 <h1 id="bugzilla">Update Bugzilla</h1>
605
606 <p>
607 Parse through the bugreports as listed in the docs/relnotes/X.Y.Z.html
608 document.
609 <br>
610 If there's outstanding action, close the bug referencing the commit ID which
611 addresses the bug and mention the Mesa version that has the fix.
612 </p>
613
614 <p>
615 Note: the above is not applicable to all the reports, so use common sense.
616 </p>
617
618
619 </div>
620 </body>
621 </html>