<html lang="en">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
- <title>Releasing process</title>
+ <title>Releasing Process</title>
<link rel="stylesheet" type="text/css" href="mesa.css">
</head>
<body>
<div class="header">
- <h1>The Mesa 3D Graphics Library</h1>
+ The Mesa 3D Graphics Library
</div>
<iframe src="contents.html"></iframe>
<div class="content">
-<h1>Releasing process</h1>
+
+<h1>Releasing Process</h1>
<ul>
-<li><a href="#overview">Overview</a>
-<li><a href="#schedule">Release schedule</a>
-<li><a href="#pickntest">Cherry-pick and test</a>
-<li><a href="#branch">Making a branchpoint</a>
-<li><a href="#prerelease">Pre-release announcement</a>
-<li><a href="#release">Making a new release</a>
-<li><a href="#announce">Announce the release</a>
-<li><a href="#website">Update the mesa3d.org website</a>
-<li><a href="#bugzilla">Update Bugzilla</a>
+<li><a href="#overview">Overview</a></li>
+<li><a href="#schedule">Release schedule</a></li>
+<li><a href="#pickntest">Cherry-pick and test</a></li>
+<li><a href="#stagingbranch">Staging branch</a></li>
+<li><a href="#branch">Making a branchpoint</a></li>
+<li><a href="#release">Making a new release</a></li>
+<li><a href="#announce">Announce the release</a></li>
+<li><a href="#gitlab">Update Gitlab Issues</a></li>
</ul>
-<h1 id="overview">Overview</h1>
+
+<h2 id="overview">Overview</h2>
<p>
This document uses the convention X.Y.Z for the release number with X.Y being
the stable branch name.
-<br>
+</p>
+
+<p>
Mesa provides feature and bugfix releases. Former use zero as patch version (Z),
while the latter have a non-zero one.
</p>
For example:
</p>
<pre>
- Mesa 10.1.0 - 10.1 branch, feature
- Mesa 10.1.4 - 10.1 branch, bugfix
- Mesa 12.0.0 - 12.0 branch, feature
- Mesa 12.0.2 - 12.0 branch, bugfix
+Mesa 10.1.0 - 10.1 branch, feature
+Mesa 10.1.4 - 10.1 branch, bugfix
+Mesa 12.0.0 - 12.0 branch, feature
+Mesa 12.0.2 - 12.0 branch, bugfix
</pre>
-<h1 id="schedule">Release schedule</h1>
+
+<h2 id="schedule">Release schedule</h2>
+
+<p>
+Releases should happen on Wednesdays. Delays can occur although those
+should be kept to a minimum.
+</p>
<p>
-Releases should happen on Fridays. Delays can occur although those should be keep
-to a minimum.
-<br>
-See our <a href="release-calendar.html" target="_parent">calendar</a> for the
+See our <a href="release-calendar.html" target="_parent">calendar</a>
+for information about how the release schedule is planned, and the
date and other details for individual releases.
</p>
<h2>Feature releases</h2>
<ul>
-<li>Available approximately every three months.
+<li>Available approximately every three months.</li>
<li>Initial timeplan available 2-4 weeks before the planned branchpoint (rc1)
-on the mesa-announce@ mailing list.
-<li>A <a href="#prerelease">pre-release</a> announcement should be available
-approximately 24 hours before the final (non-rc) release.
+on the mesa-announce@ mailing list.</li>
+<li>Typically, the final release will happen after 4
+candidates. Additional ones may be needed in order to resolve blocking
+regressions, though.</li>
</ul>
<h2>Stable releases</h2>
<ul>
-<li>Normally available once every two weeks.
-<li>Only the latest branch has releases. See note below.
-<li>A <a href="#prerelease">pre-release</a> announcement should be available
-approximately 48 hours before the actual release.
+<li>Normally available once every two weeks.</li>
+<li>Only the latest branch has releases. See note below.</li>
</ul>
<p>
Note: There is one or two releases overlap when changing branches. For example:
-<br>
+</p>
+
+<p>
The final release from the 12.0 series Mesa 12.0.5 will be out around the same
time (or shortly after) 13.0.1 is out.
</p>
-<h1 id="pickntest">Cherry-picking and testing</h1>
+<p>
+This also involves that, as a final release may be delayed due to the
+need of additional candidates to solve some blocking regression(s),
+the release manager might have to update
+the <a href="release-calendar.html" target="_parent">calendar</a> with
+additional bug fix releases of the current stable branch.
+</p>
+
+
+<h2 id="pickntest">Cherry-picking and testing</h2>
<p>
Commits nominated for the active branch are picked as based on the
<a href="submittingpatches.html#criteria" target="_parent">criteria</a> as
described in the same section.
+</p>
<p>
-Maintainer is responsible for testing in various possible permutations of
-the autoconf and scons build.
+Nominations happen via special tags in the commit messages, and via gitlab
+merge requests against the staging branches. There are special scripts used
+to read the tags.
</p>
-<h2>Cherry-picking and build/check testing</h2>
-
-<p>Done continuously up-to the <a href="#prerelease">pre-release</a> announcement.</p>
-
<p>
-As an exception, patches can be applied up-to the last ~1h before the actual
-release. This is made <strong>only</strong> with explicit permission/request,
-and the patch <strong>must</strong> be very well contained. Thus it cannot
-affect more than one driver/subsystem.
+The maintainer should watch or be in contact with the Intel CI team, as well
+as watch the gitlab CI for regressions.
</p>
+
<p>
-Currently Ilia Mirkin and AMD devs have requested "permanent" exception.
+Cherry picking should be done with the '-x' switch (to automatically add
+"cherry picked from ..." to the commit message):
</p>
+<code>
+git cherry-pick -x abcdef12345667890
+</code>
+
+<p>
+Developers can request, <em>as an exception</em>, patches to be applied up-to
+the last one hour before the actual release. This is made <strong>only</strong>
+with explicit permission/request, and the patch <strong>must</strong> be very
+well contained. Thus it cannot affect more than one driver/subsystem.
+</p>
+<p>Following developers have requested permanent exception</p>
<ul>
-<li>make distcheck, scons and scons check must pass
-<li>Testing with different version of system components - LLVM and others is also
-performed where possible.
+<li><em>Ilia Mirkin</em></li>
+<li><em>AMD team</em></li>
</ul>
+
+<p>The gitlab CI must pass.</p>
+
<p>
-Achieved by combination of local ad-hoc scripts and AppVeyor plus Travis-CI,
-the latter as part of their Github integration.
+For Windows related changes, the main contact point is Brian
+Paul. Jose Fonseca can also help as a fallback contact.
</p>
+
<p>
-<strong>Note:</strong> If a patch in the current queue needs any additional
-fix(es), then they should be squashed together.
-<br>
-The commit messages and the <code>cherry picked from</code> tags must be preserved.
+For Android related changes, the main contact is Tapani
+Pälli. Mauro Rossi is collaborating with android-x86 and may
+provide feedback about the build status in that project.
+</p>
+
+<p>
+For MacOSX related changes, Jeremy Huddleston Sequoia is currently a
+good contact point.
</p>
+
<p>
-This should be noted in the <a href="#prerelease">pre-announce</a> email.
+<strong>Note:</strong> If a patch in the current queue needs any additional
+fix(es), then they should be squashed together. The commit messages and the
+"<code>cherry picked from</code>"-tags must be preserved.
+</p>
+
<pre>
- git show b10859ec41d09c57663a258f43fe57c12332698e
+git show b10859ec41d09c57663a258f43fe57c12332698e
- commit b10859ec41d09c57663a258f43fe57c12332698e
- Author: Jonas Pfeil <pfeiljonas@gmx.de>
- Date: Wed Mar 1 18:11:10 2017 +0100
+commit b10859ec41d09c57663a258f43fe57c12332698e
+Author: Jonas Pfeil <pfeiljonas@gmx.de>
+Date: Wed Mar 1 18:11:10 2017 +0100
- ralloc: Make sure ralloc() allocations match malloc()'s alignment.
+ ralloc: Make sure ralloc() allocations match malloc()'s alignment.
- The header of ralloc needs to be aligned, because the compiler assumes
- ...
+ The header of ralloc needs to be aligned, because the compiler assumes
+ ...
- (cherry picked from commit cd2b55e536dc806f9358f71db438dd9c246cdb14)
+ (cherry picked from commit cd2b55e536dc806f9358f71db438dd9c246cdb14)
- Squashed with commit:
+ Squashed with commit:
- ralloc: don't leave out the alignment factor
+ ralloc: don't leave out the alignment factor
- Experimentation shows that without alignment factor gcc and clang choose
- ...
+ Experimentation shows that without alignment factor gcc and clang choose
+ ...
- (cherry picked from commit ff494fe999510ea40e3ed5827e7818550b6de126)
+ (cherry picked from commit ff494fe999510ea40e3ed5827e7818550b6de126)
</pre>
-</p>
<h2>Regression/functionality testing</h2>
-<p>
-Less often (once or twice), shortly before the pre-release announcement.
-Ensure that testing is redone if Intel devs have requested an exception, as per above.
-</p>
<ul>
-<li><em>no regressions should be observed for Piglit/dEQP/CTS/Vulkan on Intel platforms</em>
+<li><em>no regressions should be observed for Piglit/dEQP/CTS/Vulkan on Intel platforms</em></li>
<li><em>no regressions should be observed for Piglit using the swrast, softpipe
-and llvmpipe drivers</em>
+and llvmpipe drivers</em></li>
</ul>
+
+<h2 id="stagingbranch">Staging branch</h2>
+
+<p>
+A live branch, which contains the currently merge/rejected patches is available
+in the main repository under <code>staging/X.Y</code>. For example:
+</p>
+<pre>
+staging/18.1 - WIP branch for the 18.1 series
+staging/18.2 - WIP branch for the 18.2 series
+</pre>
+
<p>
-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.
+Notes:
</p>
+<ul>
+<li>People are encouraged to test the staging branch and report regressions.</li>
+<li>The branch history is not stable and it <strong>will</strong> be rebased,</li>
+</ul>
-<h1 id="branch">Making a branchpoint</h1>
+<h2 id="branch">Making a branchpoint</h2>
<p>
A branchpoint is made such that new development can continue in parallel to
</p>
<p>
-Note: Before doing a branch ensure that basic build and <code>make check</code>
-testing is done and there are little to-no issues.
-<br>
-Ideally all of those should be tackled already.
+Note: Before doing a branch ensure that basic build and <code>meson test</code>
+testing is done and there are little to-no issues. Ideally all of those should
+be tackled already.
</p>
<p>
To setup the branchpoint:
</p>
<pre>
- git checkout master # make sure we're in master first
- git tag -s X.Y-branchpoint -m "Mesa X.Y branchpoint"
- git checkout -b X.Y
- git checkout master
- $EDITOR VERSION # bump the version number
- git commit -as
- cp docs/relnotes/{X.Y,X.Y+1}.html # copy/create relnotes template
- git commit -as
- git push origin X.Y-branchpoint X.Y
+git checkout master # make sure we're in master first
+git tag -s X.Y-branchpoint -m "Mesa X.Y branchpoint"
+git checkout -b X.Y
+git checkout master
+$EDITOR VERSION # bump the version number
+git commit -as
+truncate docs/relnotes/new_features.txt
+git commit -a
+git push origin X.Y-branchpoint X.Y
</pre>
<p>
Now go to
-<a href="https://bugs.freedesktop.org/editversions.cgi?action=add&product=Mesa" target="_parent">Bugzilla</a> and add the new Mesa version X.Y.
+<a href="https://gitlab.freedesktop.org/mesa/mesa/-/milestones" target="_parent">gitlab</a> and add the new Mesa version X.Y.
</p>
+
<p>
Check that there are no distribution breaking changes and revert them if needed.
For example: files being overwritten on install, etc. Happens extremely rarely -
we had only one case so far (see commit 2ced8eb136528914e1bf4e000dea06a9d53c7e04).
</p>
-<p>
-Proceed to <a href="#release">release</a> -rc1.
-</p>
-<h1 id="prerelease">Pre-release announcement</h1>
-
-<p>
-It comes shortly after outstanding patches in the respective branch are pushed.
-Developers can check, in brief, what's the status of their patches. They,
-alongside very early testers, are strongly encouraged to test the branch and
-report any regressions.
-<br>
-It is followed by a brief period (normally 24 or 48 hours) before the actual
-release is made.
-</p>
-
-<h2>Terminology used</h2>
-<ul><li>Nominated</ul>
-<p>
-Patch that is nominated but yet to to merged in the patch queue/branch.
-</p>
-
-<ul><li>Queued</ul>
-<p>
-Patch is in the queue/branch and will feature in the next release.
-Barring reported regressions or objections from developers.
-</p>
-
-<ul><li>Rejected</ul>
-<p>
-Patch does not fit the
-<a href="submittingpatches.html#criteria" target="_parent">criteria</a> and
-is followed by a brief information.
-<br>
-The release maintainer is human so if you believe you've spotted a mistake do
-let them know.
-</p>
-
-<h2>Format/template</h2>
-<pre>
-Subject: [ANNOUNCE] Mesa X.Y.Z release candidate
-To: mesa-announce@...
-Cc: mesa-dev@...
-
-Hello list,
-
-The candidate for the Mesa X.Y.Z is now available. Currently we have:
- - NUMBER queued
- - NUMBER nominated (outstanding)
- - and NUMBER rejected patches
-
-BRIEF SUMMARY OF CHANGES
-
-Take a look at section "Mesa stable queue" for more information.
-
-
-Testing reports/general approval
---------------------------------
-Any testing reports (or general approval of the state of the branch) will be
-greatly appreciated.
-
-The plan is to have X.Y.Z this DAY (DATE), around or shortly after TIME.
-
-If you have any questions or suggestions - be that about the current patch
-queue or otherwise, please go ahead.
-
-
-Trivial merge conflicts
------------------------
-List of commits where manual intervention was required.
-Keep the authors in the CC list.
-
-commit SHA
-Author: AUTHOR
-
- COMMIT SUMMARY
-
- CHERRY PICKED FROM
-
-
-For example:
-
-commit 990f395e007c3204639daa34efc3049f350ee819
-Author: Emil Velikov <emil.velikov@collabora.com>
-
- anv: automake: cleanup the generated json file during make clean
-
- (cherry picked from commit 8df581520a823564be0ab5af7dbb7d501b1c9670)
-
-
-Cheers,
-Emil
-
-
-Mesa stable queue
------------------
-
-Nominated (NUMBER)
-==================
-
-AUTHOR (NUMBER):
- SHA COMMIT SUMMARY
-
-For example:
-
-Dave Airlie (1):
- 2de85eb radv: fix texturesamples to handle single sample case
-
-
-Queued (NUMBER)
-===============
-
-AUTHOR (NUMBER):
- COMMIT SUMMARY
-
-For example:
-
-Jonas Pfeil (1):
- ralloc: Make sure ralloc() allocations match malloc()'s alignment.
-Squashed with
- ralloc: don't leave out the alignment factor
-
-Rejected (NUMBER)
-=================
-
-Rejected (11)
-=============
-
-AUTHOR (NUMBER):
- SHA COMMIT SUMMARY
-
-Reason: ...
-</pre>
-
-<h1 id="release">Making a new release</h1>
+<h2 id="release">Making a new release</h2>
<p>
These are the instructions for making a new Mesa release.
</p>
<h3>Get latest source files</h3>
+
<p>
Ensure the latest code is available - both in your local master and the
relevant branch.
</p>
-<h3>Perform basic testing</h3>
+<h3 id="basictesting">Perform basic testing</h3>
+
<p>
Most of the testing should already be done during the
-<a href="#pickntest">cherry-pick</a> and
-<a href="#prerelease">pre-announce</a> stages.
-
+<a href="#pickntest">cherry-pick</a>
So we do a quick 'touch test'
+</p>
+
<ul>
-<li>make distcheck (you can omit this if you're not using --dist below)
-<li>scons (from release tarball)
-<li>the produced binaries work
+<li>meson dist</li>
+<li>scons (from release tarball)</li>
+<li>the produced binaries work</li>
</ul>
<p>
-Here is one solution that I've been using.
+ Here is one solution:
</p>
<pre>
- git clean -fXd; git clean -nxd
- read # quick cross check any outstanding files
- export __version=`cat VERSION`
- export __mesa_root=../
- export __build_root=./foo
- chmod 755 -fR $__build_root; rm -rf $__build_root
- mkdir -p $__build_root && cd $__build_root
-
- $__mesa_root/autogen.sh && make -j2 distcheck
-
- # Build check the tarballs (scons, linux)
- tar -xaf mesa-$__version.tar.xz && cd mesa-$__version
- scons
- cd .. && rm -rf mesa-$__version
-
- # Build check the tarballs (scons, windows/mingw)
- tar -xaf mesa-$__version.tar.xz && cd mesa-$__version
- scons platform=windows toolchain=crossmingw
- cd .. && rm -rf mesa-$__version
-
- # Test the automake binaries
- tar -xaf mesa-$__version.tar.xz && cd mesa-$__version
- ./configure \
- --with-dri-drivers=i965,swrast \
- --with-gallium-drivers=swrast \
- --with-vulkan-drivers=intel \
- --enable-llvm-shared-libs \
- --enable-llvm \
- --enable-glx-tls \
- --enable-gbm \
- --enable-egl \
- --with-egl-platforms=x11,drm,wayland
- make -j2 && DESTDIR=`pwd`/test make -j6 install
- __glxinfo_cmd='glxinfo 2>&1 | egrep -o "Mesa.*|Gallium.*|.*dri\.so"'
- __glxgears_cmd='glxgears 2>&1 | grep -v "configuration file"'
- __es2info_cmd='es2_info 2>&1 | egrep "GL_VERSION|GL_RENDERER|.*dri\.so"'
- __es2gears_cmd='es2gears_x11 2>&1 | grep -v "configuration file"'
- export LD_LIBRARY_PATH=`pwd`/test/usr/local/lib/
- export LIBGL_DRIVERS_PATH=`pwd`/test/usr/local/lib/dri/
- export LIBGL_DEBUG=verbose
- eval $__glxinfo_cmd
- eval $__glxgears_cmd
- eval $__es2info_cmd
- eval $__es2gears_cmd
- export LIBGL_ALWAYS_SOFTWARE=1
- eval $__glxinfo_cmd
- eval $__glxgears_cmd
- eval $__es2info_cmd
- eval $__es2gears_cmd
- export LIBGL_ALWAYS_SOFTWARE=1
- export GALLIUM_DRIVER=softpipe
- eval $__glxinfo_cmd
- eval $__glxgears_cmd
- eval $__es2info_cmd
- eval $__es2gears_cmd
- # Smoke test DOTA2
- unset LD_LIBRARY_PATH
- unset LIBGL_DRIVERS_PATH
- unset LIBGL_DEBUG
- unset LIBGL_ALWAYS_SOFTWARE
- export VK_ICD_FILENAMES=`pwd`/src/intel/vulkan/dev_icd.json
- steam steam://rungameid/570 -vconsole -vulkan
+__glxgears_cmd='glxgears 2>&1 | grep -v "configuration file"'
+__es2info_cmd='es2_info 2>&1 | egrep "GL_VERSION|GL_RENDERER|.*dri\.so"'
+__es2gears_cmd='es2gears_x11 2>&1 | grep -v "configuration file"'
+test "x$LD_LIBRARY_PATH" != 'x' && __old_ld="$LD_LIBRARY_PATH"
+export LD_LIBRARY_PATH=`pwd`/test/usr/local/lib/:"${__old_ld}"
+export LIBGL_DRIVERS_PATH=`pwd`/test/usr/local/lib/dri/
+export LIBGL_DEBUG=verbose
+eval $__glxinfo_cmd
+eval $__glxgears_cmd
+eval $__es2info_cmd
+eval $__es2gears_cmd
+export LIBGL_ALWAYS_SOFTWARE=true
+eval $__glxinfo_cmd
+eval $__glxgears_cmd
+eval $__es2info_cmd
+eval $__es2gears_cmd
+export LIBGL_ALWAYS_SOFTWARE=true
+export GALLIUM_DRIVER=softpipe
+eval $__glxinfo_cmd
+eval $__glxgears_cmd
+eval $__es2info_cmd
+eval $__es2gears_cmd
+# Smoke test DOTA2
+unset LD_LIBRARY_PATH
+test "x$__old_ld" != 'x' && export LD_LIBRARY_PATH="$__old_ld" && unset __old_ld
+unset LIBGL_DRIVERS_PATH
+unset LIBGL_DEBUG
+unset LIBGL_ALWAYS_SOFTWARE
+unset GALLIUM_DRIVER
+export VK_ICD_FILENAMES=`pwd`/test/usr/local/share/vulkan/icd.d/intel_icd.x86_64.json
+steam steam://rungameid/570 -vconsole -vulkan
+unset VK_ICD_FILENAMES
</pre>
-<h3>Update version in file VERSION</h3>
-
-<p>
-Increment the version contained in the file VERSION at Mesa's top-level, then
-commit this change.
-</p>
-
<h3>Create release notes for the new release</h3>
<p>
-Create a new file docs/relnotes/X.Y.Z.html, (follow the style of the previous
-release notes). Note that the sha256sums section of the release notes should
-be empty (TBD) at this point.
-</p>
-
-<p>
-Two scripts are available to help generate portions of the release notes:
+The release notes are completely generated by the
+<code>bin/gen_release_notes.py</code> script. Simply run this script before
+bumping the version, and commit the results.
-<pre>
- ./bin/bugzilla_mesa.sh
- ./bin/shortlog_mesa.sh
-</pre>
+The only thing left to do is add the sha256 sums.
+</p>
<p>
-The first script identifies commits that reference bugzilla bugs and obtains
-the descriptions of those bugs from bugzilla. The second script generates a
-log of all commits. In both cases, HTML-formatted lists are printed to stdout
-to be included in the release notes.
+Increment the version contained in the file VERSION at Mesa's top-level, then
+commit this change.
</p>
<p>
Commit these changes and push the branch.
</p>
+
<pre>
- git push origin HEAD
+git push origin HEAD
</pre>
<p>
Start the release process.
</p>
+
<pre>
- ../relative/path/to/release.sh . # append --dist if you've already done distcheck above
+../relative/path/to/release.sh . # append --dist if you've already done distcheck above
</pre>
<p>
<h3>Add the sha256sums to the release notes</h3>
<p>
-Edit docs/relnotes/X.Y.Z.html to add the sha256sums as available in the mesa-X.Y.Z.announce template. Commit this change.
+Edit docs/relnotes/X.Y.Z.html to add the sha256sum as available in the mesa-X.Y.Z.announce template. Commit this change.
</p>
<h3>Back on mesa master, add the new release notes into the tree</h3>
</p>
<pre>
- git cherry-pick -x X.Y~1
- git cherry-pick -x X.Y
+git cherry-pick -x X.Y~1
+git cherry-pick -x X.Y
</pre>
-<p>
-Also, edit docs/relnotes.html to add a link to the new release notes, and edit
-docs/index.html to add a news entry. Then commit and push:
+<p>Then run the <pre>./bin/post_version.py X.Y.Z</pre>, where X.Y.Z is the
+version you just made. This will updated docs/relnotes.html,
+docs/index.html, and docs/release-calendar.html. It will then generate
+a git commit automatically. Check that everything looks correct and push:
</p>
<pre>
- git commit -as -m "docs: add news item and link release notes for X.Y.Z"
git push origin master X.Y
</pre>
-<h1 id="announce">Announce the release</h1>
+<h2 id="announce">Announce the release</h2>
+
<p>
Use the generated template during the releasing process.
</p>
-
-<h1 id="website">Update the mesa3d.org website</h1>
-
<p>
-As the hosting was moved to freedesktop, git hooks are deployed to update the
-website. Manually check that it is updated 5-10 minutes after the final <code>git push</code>
+Again, pay attention to add a note to warn about a final release in a
+series, if that is the case.
</p>
-<h1 id="bugzilla">Update Bugzilla</h1>
+
+<h2 id="gitlab">Update gitlab issues</h2>
<p>
-Parse through the bugreports as listed in the docs/relnotes/X.Y.Z.html
-document.
-<br>
-If there's outstanding action, close the bug referencing the commit ID which
-addresses the bug and mention the Mesa version that has the fix.
+Parse through the bug reports as listed in the docs/relnotes/X.Y.Z.html
+document. If there's outstanding action, close the bug referencing the commit
+ID which addresses the bug and mention the Mesa version that has the fix.
</p>
<p>
projects / mesa.git / blobdiff