1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
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">
11 <h1>The Mesa
3D Graphics Library
</h1>
14 <iframe src=
"contents.html"></iframe>
18 <h1>Releasing process
</h1>
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=
"#stagingbranch">Staging branch
</a>
25 <li><a href=
"#branch">Making a branchpoint
</a>
26 <li><a href=
"#prerelease">Pre-release announcement
</a>
27 <li><a href=
"#release">Making a new release
</a>
28 <li><a href=
"#announce">Announce the release
</a>
29 <li><a href=
"#website">Update the mesa3d.org website
</a>
30 <li><a href=
"#bugzilla">Update Bugzilla
</a>
34 <h1 id=
"overview">Overview
</h1>
37 This document uses the convention X.Y.Z for the release number with X.Y being
38 the stable branch name.
40 Mesa provides feature and bugfix releases. Former use zero as patch version (Z),
41 while the latter have a non-zero one.
48 Mesa
10.1.0 -
10.1 branch, feature
49 Mesa
10.1.4 -
10.1 branch, bugfix
50 Mesa
12.0.0 -
12.0 branch, feature
51 Mesa
12.0.2 -
12.0 branch, bugfix
55 <h1 id=
"schedule">Release schedule
</h1>
58 Releases should happen on Wednesdays. Delays can occur although those
59 should be keep to a minimum.
61 See our
<a href=
"release-calendar.html" target=
"_parent">calendar
</a> for the
62 date and other details for individual releases.
65 <h2>Feature releases
</h2>
67 <li>Available approximately every three months.
68 <li>Initial timeplan available
2-
4 weeks before the planned branchpoint (rc1)
69 on the mesa-announce@ mailing list.
70 <li>A
<a href=
"#prerelease">pre-release
</a> announcement should be available
71 approximately
24 hours before the final (non-rc) release.
74 <h2>Stable releases
</h2>
76 <li>Normally available once every two weeks.
77 <li>Only the latest branch has releases. See note below.
78 <li>A
<a href=
"#prerelease">pre-release
</a> announcement should be available
79 approximately
48 hours before the actual release.
83 Note: There is one or two releases overlap when changing branches. For example:
85 The final release from the
12.0 series Mesa
12.0.5 will be out around the same
86 time (or shortly after)
13.0.1 is out.
90 <h1 id=
"pickntest">Cherry-picking and testing
</h1>
93 Commits nominated for the active branch are picked as based on the
94 <a href=
"submittingpatches.html#criteria" target=
"_parent">criteria
</a> as
95 described in the same section.
99 Nomination happens in the mesa-stable@ mailing list. However,
100 maintainer is responsible of checking for forgotten candidates in the
101 master branch. This is achieved by a combination of ad-hoc scripts and
102 a casual search for terms such as regression, fix, broken and similar.
106 Maintainer is also responsible for testing in various possible permutations of
107 the autoconf and scons build.
110 <h2>Cherry-picking and build/check testing
</h2>
112 <p>Done continuously up-to the
<a href=
"#prerelease">pre-release
</a> announcement.
</p>
115 Developers can request,
<em>as an exception
</em>, patches to be applied up-to
116 the last one hour before the actual release. This is made
<strong>only
</strong>
117 with explicit permission/request, and the patch
<strong>must
</strong> be very
118 well contained. Thus it cannot affect more than one driver/subsystem.
121 <p>Following developers have requested permanent exception
</p>
123 <li><em>Ilia Mirkin
</em>
124 <li><em>AMD team
</em>
127 <p>The following must pass:
</p>
129 <li>make distcheck, scons and scons check
130 <li>Testing with different version of system components - LLVM and others is also
131 performed where possible.
132 <li>As a general rule, testing with various combinations of configure
133 switches, depending on the specific patchset.
137 These are achieved by combination of
<a href=
"basictesting">local testing
</a>,
138 which includes mingw-w64 cross compilation and AppVeyor plus Travis-CI, the
139 latter two as part of their Github integration.
143 For Windows related changes, the main contact point is Brian
144 Paul. Jose Fonseca can also help as a fallback contact.
148 For Android related changes, the main contact is Tapani
149 P
älli. Mauro Rossi is collaborating with android-x86 and may
150 provide feedback about the build status in that project.
154 For MacOSX related changes, Jeremy Huddleston Sequoia is currently a
159 <strong>Note:
</strong> If a patch in the current queue needs any additional
160 fix(es), then they should be squashed together.
162 The commit messages and the
<code>cherry picked from
</code> tags must be preserved.
166 This should be noted in the
<a href=
"#prerelease">pre-announce
</a> email.
170 git show b10859ec41d09c57663a258f43fe57c12332698e
172 commit b10859ec41d09c57663a258f43fe57c12332698e
173 Author: Jonas Pfeil
<pfeiljonas@gmx.de
>
174 Date: Wed Mar
1 18:
11:
10 2017 +
0100
176 ralloc: Make sure ralloc() allocations match malloc()'s alignment.
178 The header of ralloc needs to be aligned, because the compiler assumes
181 (cherry picked from commit cd2b55e536dc806f9358f71db438dd9c246cdb14)
183 Squashed with commit:
185 ralloc: don't leave out the alignment factor
187 Experimentation shows that without alignment factor gcc and clang choose
190 (cherry picked from commit ff494fe999510ea40e3ed5827e7818550b6de126)
193 <h2>Regression/functionality testing
</h2>
196 Less often (once or twice), shortly before the pre-release announcement.
197 Ensure that testing is redone if Intel devs have requested an exception, as per above.
201 <li><em>no regressions should be observed for Piglit/dEQP/CTS/Vulkan on Intel platforms
</em>
202 <li><em>no regressions should be observed for Piglit using the swrast, softpipe
203 and llvmpipe drivers
</em>
207 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.
211 Installing the built driver from the pre-announced RC branch in the
212 system and making some every day's use until the release may be a good
216 <h1 id=
"stagingbranch">Staging branch
</h1>
219 A live branch, which contains the currently merge/rejected patches is available
220 in the main repository under
<code>staging/X.Y
</code>. For example:
223 staging/
18.1 - WIP branch for the
18.1 series
224 staging/
18.2 - WIP branch for the
18.2 series
231 <li>People are encouraged to test the staging branch and report regressions.
</li>
232 <li>The branch history is not stable and it
<strong>will
</strong> be rebased,
</li>
236 <h1 id=
"branch">Making a branchpoint
</h1>
239 A branchpoint is made such that new development can continue in parallel to
240 stabilisation and bugfixing.
244 Note: Before doing a branch ensure that basic build and
<code>make check
</code>
245 testing is done and there are little to-no issues.
247 Ideally all of those should be tackled already.
251 Check if the version number is going to remain as, alternatively
252 <code> git mv docs/relnotes/{current,new}.html
</code> as appropriate.
256 To setup the branchpoint:
259 git checkout master # make sure we're in master first
260 git tag -s X.Y-branchpoint -m
"Mesa X.Y branchpoint"
263 $EDITOR VERSION # bump the version number
265 cp docs/relnotes/{X.Y,X.Y+
1}.html # copy/create relnotes template
267 git push origin X.Y-branchpoint X.Y
272 <a href=
"https://bugs.freedesktop.org/editversions.cgi?action=add&product=Mesa" target=
"_parent">Bugzilla
</a> and add the new Mesa version X.Y.
276 Check that there are no distribution breaking changes and revert them if needed.
277 For example: files being overwritten on install, etc. Happens extremely rarely -
278 we had only one case so far (see commit
2ced8eb136528914e1bf4e000dea06a9d53c7e04).
282 Proceed to
<a href=
"#release">release
</a> -rc1.
286 <h1 id=
"prerelease">Pre-release announcement
</h1>
289 It comes shortly after outstanding patches in the respective branch are pushed.
290 Developers can check, in brief, what's the status of their patches. They,
291 alongside very early testers, are strongly encouraged to test the branch and
292 report any regressions.
294 It is followed by a brief period (normally
24 or
48 hours) before the actual
299 Be aware to add a note to warn about a final release in a series, if
303 <h2>Terminology used
</h2>
305 <ul><li>Nominated
</ul>
308 Patch that is nominated but yet to to merged in the patch queue/branch.
314 Patch is in the queue/branch and will feature in the next release.
315 Barring reported regressions or objections from developers.
318 <ul><li>Rejected
</ul>
321 Patch does not fit the
322 <a href=
"submittingpatches.html#criteria" target=
"_parent">criteria
</a> and
323 is followed by a brief information.
325 The release maintainer is human so if you believe you've spotted a mistake do
329 <h2>Format/template
</h2>
331 Subject: [ANNOUNCE] Mesa X.Y.Z release candidate
332 To: mesa-announce@...
337 The candidate for the Mesa X.Y.Z is now available. Currently we have:
339 - NUMBER nominated (outstanding)
340 - and NUMBER rejected patches
343 Note: this is the final anticipated release in the SERIES series. Users are
344 encouraged to migrate to the NEXT_SERIES series in order to obtain future fixes.]
346 BRIEF SUMMARY OF CHANGES
348 Take a look at section
"Mesa stable queue" for more information.
351 Testing reports/general approval
352 --------------------------------
353 Any testing reports (or general approval of the state of the branch) will be
356 The plan is to have X.Y.Z this DAY (DATE), around or shortly after TIME.
358 If you have any questions or suggestions - be that about the current patch
359 queue or otherwise, please go ahead.
362 Trivial merge conflicts
363 -----------------------
364 List of commits where manual intervention was required.
365 Keep the authors in the CC list.
377 commit
990f395e007c3204639daa34efc3049f350ee819
378 Author: Emil Velikov
<emil.velikov@collabora.com
>
380 anv: automake: cleanup the generated json file during make clean
382 (cherry picked from commit
8df581520a823564be0ab5af7dbb7d501b1c9670)
401 2de85eb radv: fix texturesamples to handle single sample case
416 ralloc: Make sure ralloc() allocations match malloc()'s alignment.
418 ralloc: don't leave out the alignment factor
432 a39ad18 configure.ac: honour LLVM_LIBDIR when linking against LLVM
434 Reason: The patch was reverted shortly after it was merged.
438 <h1 id=
"release">Making a new release
</h1>
441 These are the instructions for making a new Mesa release.
444 <h3>Get latest source files
</h3>
447 Ensure the latest code is available - both in your local master and the
451 <h3 id=
"basictesting">Perform basic testing
</h3>
454 Most of the testing should already be done during the
455 <a href=
"#pickntest">cherry-pick
</a> and
456 <a href=
"#prerelease">pre-announce
</a> stages.
457 So we do a quick 'touch test'
461 <li>make distcheck (you can omit this if you're not using --dist below)
462 <li>scons (from release tarball)
463 <li>the produced binaries work
467 Here is one solution that I've been using.
471 # Set MAKEFLAGS if you haven't already
472 git clean -fXd; git clean -nxd
473 read # quick cross check any outstanding files
474 export __version=`cat VERSION`
475 export __mesa_root=../
476 export __build_root=./foo
477 chmod
755 -fR $__build_root; rm -rf $__build_root
478 mkdir -p $__build_root
&& cd $__build_root
480 # For the native builds - such as distcheck, scons, sanity test, you
481 # may want to specify which LLVM to use:
482 # export LLVM_CONFIG=/usr/lib/llvm-
3.9/bin/llvm-config
484 # Do a full distcheck
485 $__mesa_root/autogen.sh
&& make distcheck
487 # Build check the tarballs (scons, linux)
488 tar -xaf mesa-$__version.tar.xz
&& cd mesa-$__version
490 cd ..
&& rm -rf mesa-$__version
492 # Build check the tarballs (scons, windows/mingw)
493 # Temporary drop LLVM_CONFIG, unless you have a Windows/mingw one.
494 # save_LLVM_CONFIG=`echo $LLVM_CONFIG`; unset LLVM_CONFIG
495 tar -xaf mesa-$__version.tar.xz
&& cd mesa-$__version
496 scons platform=windows toolchain=crossmingw
497 cd ..
&& rm -rf mesa-$__version
499 # Test the automake binaries
500 # Restore LLVM_CONFIG, if applicable:
501 # export LLVM_CONFIG=`echo $save_LLVM_CONFIG`; unset save_LLVM_CONFIG
502 tar -xaf mesa-$__version.tar.xz
&& cd mesa-$__version
504 --with-dri-drivers=i965,swrast \
505 --with-gallium-drivers=swrast \
506 --with-vulkan-drivers=intel \
507 --enable-llvm-shared-libs \
512 --with-platforms=x11,drm,wayland,surfaceless
513 make
&& DESTDIR=`pwd`/test make install
515 # Drop LLVM_CONFIG, if applicable:
518 __glxinfo_cmd='glxinfo
2>&1 | egrep -o
"Mesa.*|Gallium.*|.*dri\.so"'
519 __glxgears_cmd='glxgears
2>&1 | grep -v
"configuration file"'
520 __es2info_cmd='es2_info
2>&1 | egrep
"GL_VERSION|GL_RENDERER|.*dri\.so"'
521 __es2gears_cmd='es2gears_x11
2>&1 | grep -v
"configuration file"'
522 test
"x$LD_LIBRARY_PATH" != 'x'
&& __old_ld=
"$LD_LIBRARY_PATH"
523 export LD_LIBRARY_PATH=`pwd`/test/usr/local/lib/:
"${__old_ld}"
524 export LIBGL_DRIVERS_PATH=`pwd`/test/usr/local/lib/dri/
525 export LIBGL_DEBUG=verbose
530 export LIBGL_ALWAYS_SOFTWARE=true
535 export LIBGL_ALWAYS_SOFTWARE=true
536 export GALLIUM_DRIVER=softpipe
542 unset LD_LIBRARY_PATH
543 test
"x$__old_ld" != 'x'
&& export
LD_LIBRARY_PATH=
"$__old_ld" && unset __old_ld
544 unset LIBGL_DRIVERS_PATH
546 unset LIBGL_ALWAYS_SOFTWARE
548 export VK_ICD_FILENAMES=`pwd`/src/intel/vulkan/dev_icd.json
549 steam steam://rungameid/
570 -vconsole -vulkan
550 unset VK_ICD_FILENAMES
553 <h3>Update version in file VERSION
</h3>
556 Increment the version contained in the file VERSION at Mesa's top-level, then
560 <h3>Create release notes for the new release
</h3>
563 Create a new file docs/relnotes/X.Y.Z.html, (follow the style of the previous
564 release notes). Note that the sha256sums section of the release notes should
565 be empty (TBD) at this point.
569 Two scripts are available to help generate portions of the release notes:
573 ./bin/bugzilla_mesa.sh
574 ./bin/shortlog_mesa.sh
578 The first script identifies commits that reference bugzilla bugs and obtains
579 the descriptions of those bugs from bugzilla. The second script generates a
580 log of all commits. In both cases, HTML-formatted lists are printed to stdout
581 to be included in the release notes.
585 Commit these changes and push the branch.
593 <h3>Use the release.sh script from xorg
<a href=
"https://cgit.freedesktop.org/xorg/util/modular/">util-modular
</a></h3>
596 Start the release process.
600 # For the dist/distcheck, you may want to specify which LLVM to use:
601 # export LLVM_CONFIG=/usr/lib/llvm-
3.9/bin/llvm-config
602 ../relative/path/to/release.sh . # append --dist if you've already done distcheck above
606 Pay close attention to the prompts as you might be required to enter your GPG
607 and SSH passphrase(s) to sign and upload the files, respectively.
610 <h3>Add the sha256sums to the release notes
</h3>
613 Edit docs/relnotes/X.Y.Z.html to add the sha256sums as available in the mesa-X.Y.Z.announce template. Commit this change.
616 <h3>Back on mesa master, add the new release notes into the tree
</h3>
619 Something like the following steps will do the trick:
623 git cherry-pick -x X.Y~
1
624 git cherry-pick -x X.Y
628 Also, edit docs/relnotes.html to add a link to the new release notes,
629 edit docs/index.html to add a news entry and a note in case of the
630 last release in a series, and remove the version from
631 docs/release-calendar.html. Then commit and push:
635 git commit -as -m
"docs: update calendar, add news item and link release notes for X.Y.Z"
636 git push origin master X.Y
640 <h1 id=
"announce">Announce the release
</h1>
643 Use the generated template during the releasing process.
647 Again, pay attention to add a note to warn about a final release in a
648 series, if that is the case.
652 <h1 id=
"website">Update the mesa3d.org website
</h1>
655 As the hosting was moved to freedesktop, git hooks are deployed to update the
656 website. Manually check that it is updated
5-
10 minutes after the final
<code>git push
</code>
660 <h1 id=
"bugzilla">Update Bugzilla
</h1>
663 Parse through the bugreports as listed in the docs/relnotes/X.Y.Z.html
666 If there's outstanding action, close the bug referencing the commit ID which
667 addresses the bug and mention the Mesa version that has the fix.
671 Note: the above is not applicable to all the reports, so use common sense.