| <!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"> |
| The Mesa 3D Graphics Library |
| </div> |
| |
| <iframe src="contents.html"></iframe> |
| <div class="content"> |
| |
| |
| <h1>Releasing Process</h1> |
| |
| <ul> |
| <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> |
| |
| |
| <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. |
| </p> |
| |
| <p> |
| 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> |
| |
| |
| <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> |
| 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> |
| <li>Initial timeplan available 2-4 weeks before the planned branchpoint (rc1) |
| 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> |
| <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: |
| </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> |
| |
| <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> |
| 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> |
| |
| <p> |
| The maintainer should watch or be in contact with the Intel CI team, as well |
| as watch the gitlab CI for regressions. |
| </p> |
| |
| <p> |
| 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><em>Ilia Mirkin</em></li> |
| <li><em>AMD team</em></li> |
| </ul> |
| |
| <p>The gitlab CI must pass.</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. The commit messages and the |
| "<code>cherry picked from</code>"-tags must be preserved. |
| </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> |
| |
| <ul> |
| <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></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> |
| 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> |
| |
| |
| <h2 id="branch">Making a branchpoint</h2> |
| |
| <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>meson test</code> |
| testing is done and there are little to-no issues. 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 |
| 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://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> |
| |
| <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 id="basictesting">Perform basic testing</h3> |
| |
| <p> |
| Most of the testing should already be done during the |
| <a href="#pickntest">cherry-pick</a> |
| So we do a quick 'touch test' |
| </p> |
| |
| <ul> |
| <li>meson dist</li> |
| <li>scons (from release tarball)</li> |
| <li>the produced binaries work</li> |
| </ul> |
| |
| <p> |
| Here is one solution: |
| </p> |
| |
| <pre> |
| __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>Create release notes for the new release</h3> |
| |
| <p> |
| 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. |
| |
| The only thing left to do is add the sha256 sums. |
| </p> |
| |
| <p> |
| 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 |
| </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> |
| ../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 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> |
| 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>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 push origin master X.Y |
| </pre> |
| |
| |
| <h2 id="announce">Announce the release</h2> |
| |
| <p> |
| Use the generated template during the releasing process. |
| </p> |
| |
| <p> |
| Again, pay attention to add a note to warn about a final release in a |
| series, if that is the case. |
| </p> |
| |
| |
| <h2 id="gitlab">Update gitlab issues</h2> |
| |
| <p> |
| 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> |
| Note: the above is not applicable to all the reports, so use common sense. |
| </p> |
| |
| |
| </div> |
| </body> |
| </html> |