diff options
| author | Jonathan Gray <jsg@cvs.openbsd.org> | 2018-10-23 06:36:00 +0000 |
|---|---|---|
| committer | Jonathan Gray <jsg@cvs.openbsd.org> | 2018-10-23 06:36:00 +0000 |
| commit | b65fcab046d3a1b6b6ac315720df220925c5322e (patch) | |
| tree | ff73dcc383ac0799c655ff6194cda9dacb75dde9 /lib/mesa/docs/releasing.html | |
| parent | 18d6381c51e253e4c41c62619f80d9ce745b95c8 (diff) | |
Merge Mesa 17.3.9
Mesa 18.x needs an ld with build-id for at least the intel code
Mesa 18.2 assumes linux only memfd syscalls in intel code
Tested by matthieu@, kettenis@ and myself on a variety of hardware and
architectures. ok kettenis@
Diffstat (limited to 'lib/mesa/docs/releasing.html')
| -rw-r--r-- | lib/mesa/docs/releasing.html | 625 |
1 files changed, 625 insertions, 0 deletions
diff --git a/lib/mesa/docs/releasing.html b/lib/mesa/docs/releasing.html new file mode 100644 index 000000000..66742b0bc --- /dev/null +++ b/lib/mesa/docs/releasing.html @@ -0,0 +1,625 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html lang="en"> +<head> + <meta http-equiv="content-type" content="text/html; charset=utf-8"> + <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> +</div> + +<iframe src="contents.html"></iframe> +<div class="content"> + + +<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> +</ul> + + +<h1 id="overview">Overview</h1> + +<p> +This document uses the convention X.Y.Z for the release number with X.Y being +the stable branch name. +<br> +Mesa provides feature and bugfix releases. Former use zero as patch version (Z), +while the latter have a non-zero one. +</p> + +<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 +</pre> + + +<h1 id="schedule">Release schedule</h1> + +<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 +date and other details for individual releases. +</p> + +<h2>Feature releases</h2> +<ul> +<li>Available approximately every three months. +<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. +</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. +</ul> + +<p> +Note: There is one or two releases overlap when changing branches. For example: +<br> +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> +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> +Nomination happens in the mesa-stable@ mailing list. However, +maintainer is resposible 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. +</p> + +<p> +Maintainer is also responsible for testing in various possible permutations of +the autoconf and scons build. +</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. +</p> + +<p> +Currently Ilia Mirkin and AMD devs 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>As a general rule, testing with various combinations of configure +switches, depending on the specific patchset. +</ul> + +<p> +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. +</p> + +<p> +For Windows related changes, the main contact point is Brian +Paul. Jose Fonseca can also help as a fallback contact. +</p> + +<p> +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> +<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. +</p> + +<p> +This should be noted in the <a href="#prerelease">pre-announce</a> email. +</p> + +<pre> + git show b10859ec41d09c57663a258f43fe57c12332698e + + 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. + + The header of ralloc needs to be aligned, because the compiler assumes + ... + + (cherry picked from commit cd2b55e536dc806f9358f71db438dd9c246cdb14) + + Squashed with commit: + + ralloc: don't leave out the alignment factor + + Experimentation shows that without alignment factor gcc and clang choose + ... + + (cherry picked from commit ff494fe999510ea40e3ed5827e7818550b6de126) +</pre> + +<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 using the swrast, softpipe +and llvmpipe drivers</em> +</ul> + +<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. +</p> + +<p> +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. +</p> + + +<h1 id="branch">Making a branchpoint</h1> + +<p> +A branchpoint is made such that new development can continue in parallel to +stabilisation and bugfixing. +</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. +</p> + +<p> +Check if the version number is going to remain as, alternatively +<code> git mv docs/relnotes/{current,new}.html </code> as appropriate. +</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 +</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. +</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> + +<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> + +<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. +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 +</ul> + +<p> +Here is one solution that I've been using. +</p> + +<pre> + # 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 + tar -xaf mesa-$__version.tar.xz && cd mesa-$__version + # Restore LLVM_CONFIG, if applicable: + # export LLVM_CONFIG=`echo $save_LLVM_CONFIG`; unset save_LLVM_CONFIG + ./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 + __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 + export VK_ICD_FILENAMES=`pwd`/src/intel/vulkan/dev_icd.json + steam steam://rungameid/570 -vconsole -vulkan +</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: +</p> + +<pre> + ./bin/bugzilla_mesa.sh + ./bin/shortlog_mesa.sh +</pre> + +<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. +</p> + +<p> +Commit these changes and push the branch. +</p> + +<pre> + git push origin HEAD +</pre> + + +<h3>Use the release.sh script from xorg <a href="https://cgit.freedesktop.org/xorg/util/modular/">util-modular</a></h3> + +<p> +Start the release process. +</p> + +<pre> + # 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 +</pre> + +<p> +Pay close attention to the prompts as you might be required to enter your GPG +and SSH passphrase(s) to sign and upload the files, respectively. +</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. +</p> + +<h3>Back on mesa master, add the new release notes into the tree</h3> + +<p> +Something like the following steps will do the trick: +</p> + +<pre> + 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, +edit docs/index.html to add a news entry, and remove the version from +docs/release-calendar.html. Then commit and push: +</p> + +<pre> + git commit -as -m "docs: update calendar, 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> + +<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> +</p> + + +<h1 id="bugzilla">Update Bugzilla</h1> + +<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. +</p> + +<p> +Note: the above is not applicable to all the reports, so use common sense. +</p> + + +</div> +</body> +</html> |