Releasing process
+ +Releasing Process
-
-
- Overview -
- Release schedule -
- Cherry-pick and test -
- Making a branchpoint -
- Pre-release announcement -
- Making a new release -
- Announce the release -
- Update the mesa3d.org website -
- Update Bugzilla +
- Overview +
- Release schedule +
- Cherry-pick and test +
- Staging branch +
- Making a branchpoint +
- Making a new release +
- Announce the release +
- Update Gitlab Issues
Overview
+ +Overview
This document uses the convention X.Y.Z for the release number with X.Y being
the stable branch name.
-
+
Mesa provides feature and bugfix releases. Former use zero as patch version (Z), while the latter have a non-zero one.
@@ -42,397 +45,319 @@ while the latter have a non-zero one. For example:- 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-
Release schedule
+ +Release schedule
+ ++Releases should happen on Wednesdays. Delays can occur although those +should be kept to a minimum. +
-Releases should happen on Fridays. Delays can occur although those should be keep -to a minimum. +See our calendar +for information about how the release schedule is planned, and the +date and other details for individual releases.
Feature releases
-
-
- Available approximatelly every three months. +
- Available approximately every three months.
- Initial timeplan available 2-4 weeks before the planned branchpoint (rc1) -on the mesa-announce@ mailing list. -
- A pre-release announcement should be available -approximatelly 24 hours before the final (non-rc) release. +on the mesa-announce@ mailing list. +
- Typically, the final release will happen after 4 +candidates. Additional ones may be needed in order to resolve blocking +regressions, though.
Stable releases
-
-
- Normally available once every two weeks. -
- Only the latest branch has releases. See note below. -
- A pre-release announcement should be available -approximatelly 48 hours before the actual release. +
- Normally available once every two weeks. +
- Only the latest branch has releases. See note below.
Note: There is one or two releases overlap when changing branches. For example:
-
-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.
Cherry-picking and testing
--Commits nominated for the active branch are picked as based on the -criteria as -described in the same section. - -
-Maintainer is responsible for testing in various possible permutations of -the autoconf and scons build. +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.
-Cherry-picking and build/check testing
- -Done continuously up-to the pre-release announcement.
- --As an exception, patches can be applied up-to the last ~1h before the actual -release. This is made only with explicit permission/request, -and the patch must be very well contained. Thus it cannot -affect more than one driver/subsystem. -
-Currently Ilia Mirkin and AMD devs have requested "permanent" exception. +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 calendar with +additional bug fix releases of the current stable branch.
--
-
- make distcheck, scons and scons check must pass -
- Testing with different version of system components - LLVM and others is also -performed where possible. -
-Achieved by combination of local ad-hoc scripts and AppVeyor plus Travis-CI, -the latter as part of their Github integration. -
+Cherry-picking and testing
-Regression/functionality testing
- --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. -
--
-
- no regressions should be observed for Piglit/dEQP/CTS/Vulkan on Intel platforms -
- no regressions should be observed for Piglit using the swrast, softpipe -and llvmpipe drivers -
-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. +Commits nominated for the active branch are picked as based on the +criteria as +described in the same section.
- -Making a branchpoint
--A branchpoint is made such that new development can continue in parallel to -stabilisation and bugfixing. +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.
-Note: Before doing a branch ensure that basic build and make check
-testing is done and there are little to-no issues.
-
-Ideally all of those should be tackled already.
+The maintainer should watch or be in contact with the Intel CI team, as well
+as watch the gitlab CI for regressions.
-Check if the version number is going to remain as, alternatively
- git mv docs/relnotes/{current,new}.html
as appropriate.
+Cherry picking should be done with the '-x' switch (to automatically add
+"cherry picked from ..." to the commit message):
-To setup the branchpoint: -
-- 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 cherry-pick -x abcdef12345667890
+
-Now go to -Bugzilla and add the new Mesa version X.Y. -
--Check for rare that there are no distribution breaking changes and revert them -if needed. Extremely rare - we had only one case so far (see -commit 2ced8eb136528914e1bf4e000dea06a9d53c7e04). -
--Proceed to release -rc1. +Developers can request, as an exception, patches to be applied up-to +the last one hour before the actual release. This is made only +with explicit permission/request, and the patch must be very +well contained. Thus it cannot affect more than one driver/subsystem.
-Pre-release announcement
+Following developers have requested permanent exception
+-
+
- Ilia Mirkin +
- AMD team +
The gitlab CI must pass.
-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.
-
-It is followed by a brief period (normally 24 or 48 hours) before the actual
-release is made.
+For Windows related changes, the main contact point is Brian
+Paul. Jose Fonseca can also help as a fallback contact.
Terminology used
-- Nominated
-Patch that is nominated but yet to to merged in the patch queue/branch. +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.
-- Queued
-Patch is in the queue/branch and will feature in the next release. -Barring reported regressions or objections from developers. +For MacOSX related changes, Jeremy Huddleston Sequoia is currently a +good contact point.
-- Rejected
-Patch does not fit the
-criteria and
-is followed by a brief information.
-
-The release maintainer is human so if you believe you've spotted a mistake do
-let them know.
+Note: If a patch in the current queue needs any additional
+fix(es), then they should be squashed together. The commit messages and the
+"cherry picked from
"-tags must be preserved.
Format/template
-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 +git show b10859ec41d09c57663a258f43fe57c12332698e -Take a look at section "Mesa stable queue" for more information. +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. -Testing reports/general approval --------------------------------- -Any testing reports (or general approval of the state of the branch) will be -greatly appreciated. + The header of ralloc needs to be aligned, because the compiler assumes + ... -The plan is to have X.Y.Z this DAY (DATE), around or shortly after TIME. + (cherry picked from commit cd2b55e536dc806f9358f71db438dd9c246cdb14) -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: + Squashed with commit: -commit 990f395e007c3204639daa34efc3049f350ee819 -Author: Emil Velikov <emil.velikov@collabora.com> + ralloc: don't leave out the alignment factor - anv: automake: cleanup the generated json file during make clean - - (cherry picked from commit 8df581520a823564be0ab5af7dbb7d501b1c9670) - - -Cheers, -Emil + Experimentation shows that without alignment factor gcc and clang choose + ... + (cherry picked from commit ff494fe999510ea40e3ed5827e7818550b6de126) +-Mesa stable queue ------------------ +
Regression/functionality testing
-Nominated (NUMBER) -================== +-
+
- no regressions should be observed for Piglit/dEQP/CTS/Vulkan on Intel platforms +
- no regressions should be observed for Piglit using the swrast, softpipe +and llvmpipe drivers +
Staging branch
-For example: +
+A live branch, which contains the currently merge/rejected patches is available
+in the main repository under staging/X.Y
. For example:
+
+staging/18.1 - WIP branch for the 18.1 series +staging/18.2 - WIP branch for the 18.2 series +-Dave Airlie (1): - 2de85eb radv: fix texturesamples to handle single sample case +
+Notes: +
+-
+
- People are encouraged to test the staging branch and report regressions. +
- The branch history is not stable and it will be rebased, +
Making a branchpoint
-AUTHOR (NUMBER): - COMMIT SUMMARY ++A branchpoint is made such that new development can continue in parallel to +stabilisation and bugfixing. +
+
+Note: Before doing a branch ensure that basic build and meson test
+testing is done and there are little to-no issues. Ideally all of those should
+be tackled already.
+
+Check if the version number is going to remain as, alternatively
+ git mv docs/relnotes/{current,new}.html
as appropriate.
+
+To setup the branchpoint: +
++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 +-AUTHOR (NUMBER): - SHA COMMIT SUMMARY +
+Now go to +gitlab and add the new Mesa version X.Y. +
-Reason: ... - ++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). +
-Making a new release
+Making a new release
These are the instructions for making a new Mesa release.
Get latest source files
+Ensure the latest code is available - both in your local master and the relevant branch.
-Perform basic testing
+Perform basic testing
+Most of the testing should already be done during the -cherry-pick and -pre-announce stages. - +cherry-pick So we do a quick 'touch test' +
+-
-
- make distcheck (you can omit this if you're not using --dist below) -
- scons (from release tarball) -
- the produced binaries work +
- meson dist +
- scons (from release tarball) +
- the produced binaries work
-Here is one solution that I've been using. + Here is one solution:
- 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 --enable-llvm-shared-libs && make -j2 distcheck - - # Build check the tarballs (scons) - tar -xaf mesa-$__version.tar.xz && cd mesa-$__version && scons && cd .. - - # Test the automake binaries - rm -rf mesa-$__version - 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 - export LD_LIBRARY_PATH=`pwd`/test/usr/local/lib/ - export LIBGL_DRIVERS_PATH=`pwd`/test/usr/local/lib/dri/ - export LIBGL_DEBUG=verbose - glxinfo | egrep -o "Mesa.*" - glxgears - es2_info | egrep "GL_VERSION|GL_RENDERER" - es2gears_x11 - export LIBGL_ALWAYS_SOFTWARE=1 - glxinfo | egrep -o "Mesa.*|Gallium.*" - glxgears - es2_info | egrep "GL_VERSION|GL_RENDERER" - es2gears_x11 - export LIBGL_ALWAYS_SOFTWARE=1 - export GALLIUM_DRIVER=softpipe - glxinfo | egrep -o "Mesa.*|Gallium.*" - glxgears - es2_info | egrep "GL_VERSION|GL_RENDERER" - es2gears_x11 - # 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-
Update version in file VERSION
- --Increment the version contained in the file VERSION at Mesa's top-level, then -commit this change. -
-Create release notes for the new release
-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. -
- -
-Two scripts are available to help generate portions of the release notes:
+The release notes are completely generated by the
+bin/gen_release_notes.py
script. Simply run this script before
+bumping the version, and commit the results.
-
- ./bin/bugzilla_mesa.sh - ./bin/shortlog_mesa.sh -+The only thing left to do is add the sha256 sums. +
-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.
Commit these changes and push the branch.
+- git push origin HEAD +git push origin HEAD-
Use the release.sh script from xorg util-macros
+Use the release.sh script from xorg util-modular
-Ensure that the mesa git tree is clean via git clean -fXd
and
-start the release process.
+Start the release process.
- ../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
@@ -443,7 +368,7 @@ and SSH passphrase(s) to sign and upload the files, respectively.
Add the sha256sums to the release notes
-Edit docs/relnotes/X.Y.Z.html to add the sha256sums as availabe 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.
Back on mesa master, add the new release notes into the tree
@@ -453,55 +378,39 @@ Something like the following steps will do the trick:- 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-
-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: +
Then run the
./bin/post_version.py X.Y.Z, 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:
- git commit -as -m "docs: add news item and link release notes for X.Y.Z" git push origin master X.Y-
Announce the release
--Use the generated template during the releasing process. -
- - -Update the mesa3d.org website
+Announce the release
-NOTE: The recent release managers have not been performing this step -themselves, but leaving this to Brian Paul, (who has access to the -sourceforge.net hosting for mesa3d.org). Brian is more than willing to grant -the permission necessary to future release managers to do this step on their -own. +Use the generated template during the releasing process.
-Update the web site by copying the docs/ directory's files to
-/home/users/b/br/brianp/mesa-www/htdocs/ with:
-
-
-sftp USERNAME,mesa3d@web.sourceforge.net
-
+Again, pay attention to add a note to warn about a final release in a
+series, if that is the case.
Update Bugzilla
+Update gitlab issues
-Parse through the bugreports 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.
+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.