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.
@@ -44,49 +45,61 @@ 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 keep to a minimum.
-
-See our calendar for the
+should be kept 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 approximately 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 -approximately 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 -approximately 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.
++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. +
+ -Cherry-picking and testing
+Cherry-picking and testing
Commits nominated for the active branch are picked as based on the @@ -95,45 +108,39 @@ described in the same section.
-Nomination happens in the mesa-stable@ mailing list. However, -maintainer is responsible of checking for forgotten candidates in the -master branch. This is achieved by a combination of ad-hoc scripts and -a casual search for terms such as regression, fix, broken and similar. +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.
-Maintainer is also responsible for testing in various possible permutations of -the autoconf and scons build. +The maintainer should watch or be in contact with the Intel CI team, as well +as watch the gitlab CI for regressions.
-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. +Cherry picking should be done with the '-x' switch (to automatically add +"cherry picked from ..." to the commit message):
+
+git cherry-pick -x abcdef12345667890
+
+
-Currently Ilia Mirkin and AMD devs have requested "permanent" exception. +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.
+Following developers have requested permanent exception
-
-
- make distcheck, scons and scons check must pass -
- Testing with different version of system components - LLVM and others is also -performed where possible. -
- As a general rule, testing with various combinations of configure -switches, depending on the specific patchset. +
- Ilia Mirkin +
- AMD team
-Achieved by combination of local ad-hoc scripts, mingw-w64 cross -compilation and AppVeyor plus Travis-CI, the latter as part of their -Github integration. -
+The gitlab CI must pass.
For Windows related changes, the main contact point is Brian @@ -153,64 +160,63 @@ good contact point.
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.
-
-This should be noted in the pre-announce email.
+fix(es), then they should be squashed together. The commit messages and the
+"cherry picked from
"-tags must be preserved.
- 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)
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/dEQP/CTS/Vulkan on Intel platforms
- no regressions should be observed for Piglit using the swrast, softpipe -and llvmpipe drivers +and llvmpipe drivers
Staging branch
+
-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.
+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 +
-Installing the built driver from the pre-announced RC branch in the -system and making some every day's use until the release may be a good -idea too. +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
+Making a branchpoint
A branchpoint is made such that new development can continue in parallel to @@ -218,10 +224,9 @@ stabilisation and bugfixing.
-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.
+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.
@@ -233,20 +238,20 @@ Check if the version number is going to remain as, alternatively 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 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
Now go to -Bugzilla and add the new Mesa version X.Y. +gitlab and add the new Mesa version X.Y.
@@ -255,164 +260,7 @@ For example: files being overwritten on install, etc. Happens extremely rarely - we had only one case so far (see commit 2ced8eb136528914e1bf4e000dea06a9d53c7e04).
--Proceed to release -rc1. -
- - -Pre-release announcement
- -
-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.
-
-Be aware to add a note to warn about a final release in a series, if -that is the case. -
- -Terminology used
- -- Nominated
-Patch that is nominated but yet to to merged in the patch queue/branch. -
- -- Queued
-Patch is in the queue/branch and will feature in the next release. -Barring reported regressions or objections from developers. -
- -- 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.
-
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 - -[If applicable: -Note: this is the final anticipated release in the SERIES series. Users are -encouraged to migrate to the NEXT_SERIES series in order to obtain future fixes.] - -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 -[If applicable: -Squashed with - 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) -================= - -AUTHOR (NUMBER): - SHA COMMIT SUMMARY - -Reason: ... - -For example: - -Emil Velikov (1) - a39ad18 configure.ac: honour LLVM_LIBDIR when linking against LLVM - -Reason: The patch was reverted shortly after it was merged. -- - -
Making a new release
+Making a new release
These are the instructions for making a new Mesa release. @@ -425,137 +273,72 @@ 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:
- # Set MAKEFLAGS if you haven't already - 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 - - # For the native builds - such as distcheck, scons, sanity test, you - # may want to specify which LLVM to use: - # export LLVM_CONFIG=/usr/lib/llvm-3.9/bin/llvm-config - - # Do a full distcheck - $__mesa_root/autogen.sh && make 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) - # Temporary drop LLVM_CONFIG, unless you have a Windows/mingw one. - # save_LLVM_CONFIG=`echo $LLVM_CONFIG`; unset LLVM_CONFIG - tar -xaf mesa-$__version.tar.xz && cd mesa-$__version - scons platform=windows toolchain=crossmingw - cd .. && rm -rf mesa-$__version - - # Test the automake binaries - # Restore LLVM_CONFIG, if applicable: - # export LLVM_CONFIG=`echo $save_LLVM_CONFIG`; unset save_LLVM_CONFIG - 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-platforms=x11,drm,wayland,surfaceless - make && DESTDIR=`pwd`/test make install - - # Drop LLVM_CONFIG, if applicable: - # unset LLVM_CONFIG - - __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"' - 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`/src/intel/vulkan/dev_icd.json - steam steam://rungameid/570 -vconsole -vulkan - unset VK_ICD_FILENAMES +__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. -
+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.
--Two scripts are available to help generate portions of the release notes: +The only thing left to do is add the sha256 sums.
-- ./bin/bugzilla_mesa.sh - ./bin/shortlog_mesa.sh --
-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.
@@ -563,7 +346,7 @@ Commit these changes and push the branch.
- git push origin HEAD +git push origin HEAD@@ -574,9 +357,7 @@ Start the release process.
- # For the dist/distcheck, you may want to specify which LLVM to use: - # export LLVM_CONFIG=/usr/lib/llvm-3.9/bin/llvm-config - ../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
@@ -587,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 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.
Back on mesa master, add the new release notes into the tree
@@ -597,24 +378,22 @@ 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, -edit docs/index.html to add a news entry and a note in case of the -last release in a series, and remove the version from -docs/release-calendar.html. 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: update calendar, add news item and link release notes for X.Y.Z" git push origin master X.Y-
Announce the release
+Announce the release
Use the generated template during the releasing process. @@ -626,22 +405,12 @@ series, if that is the case.
-Update the mesa3d.org website
- -
-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 git push
-
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.