1Releasing Process 2================= 3 4Overview 5-------- 6 7This document uses the convention X.Y.Z for the release number with X.Y 8being the stable branch name. 9 10Mesa provides feature and bugfix releases. Former use zero as patch 11version (Z), while the latter have a non-zero one. 12 13For example: 14 15:: 16 17 Mesa 10.1.0 - 10.1 branch, feature 18 Mesa 10.1.4 - 10.1 branch, bugfix 19 Mesa 12.0.0 - 12.0 branch, feature 20 Mesa 12.0.2 - 12.0 branch, bugfix 21 22.. _schedule: 23 24Release schedule 25---------------- 26 27Releases should happen on Wednesdays. Delays can occur although those 28should be kept to a minimum. 29 30See our :doc:`calendar <release-calendar>` for information about how 31the release schedule is planned, and the date and other details for 32individual releases. 33 34Feature releases 35---------------- 36 37- Available approximately every three months. 38- Feature releases are branched on or around the second Wednesday of 39 January, April, July, and October. 40- Initial time plan available 2-4 weeks before the planned branchpoint 41 (rc1) on the mesa-announce@ mailing list. 42- Typically, the final release will happen after 4 candidates. 43 Additional ones may be needed in order to resolve blocking 44 regressions, though. 45 46Stable releases 47--------------- 48 49- Normally available once every two weeks. 50- Only the latest branch has releases. See note below. 51 52.. note:: 53 54 There is one or two releases overlap when changing branches. For 55 example: 56 57 The final release from the 12.0 series Mesa 12.0.5 will be out around 58 the same time (or shortly after) 13.0.1 is out. 59 60 This also involves that, as a final release may be delayed due to the 61 need of additional candidates to solve some blocking regression(s), the 62 release manager might have to update the 63 :doc:`calendar <release-calendar>` with additional bug fix releases of 64 the current stable branch. 65 66.. _pickntest: 67 68Cherry-picking and testing 69-------------------------- 70 71Commits nominated for the active branch are picked as based on the 72:ref:`criteria <criteria>` as described in the same 73section. 74 75Nominations happen via special tags in the commit messages, and via 76GitLab merge requests against the staging branches. There are special 77scripts used to read the tags. 78 79The maintainer should watch or be in contact with the Intel CI team, as 80well as watch the GitLab CI for regressions. 81 82Cherry picking should be done with the '-x' switch (to automatically add 83"cherry picked from ..." to the commit message): 84 85``git cherry-pick -x abcdef12345667890`` 86 87Developers can request, *as an exception*, patches to be applied up-to 88the last one hour before the actual release. This is made **only** with 89explicit permission/request, and the patch **must** be very well 90contained. Thus it cannot affect more than one driver/subsystem. 91 92Following developers have requested permanent exception 93 94- *Ilia Mirkin* 95- *AMD team* 96 97The GitLab CI must pass. 98 99For Windows related changes, the main contact point is Brian Paul. Jose 100Fonseca can also help as a fallback contact. 101 102For Android related changes, the main contact is Tapani Pälli. Mauro 103Rossi is collaborating with Android-x86 and may provide feedback about 104the build status in that project. 105 106For MacOSX related changes, Jeremy Huddleston Sequoia is currently a 107good contact point. 108 109.. note:: 110 111 If a patch in the current queue needs any additional fix(es), 112 then they should be squashed together. The commit messages and the 113 "``cherry picked from``"-tags must be preserved. 114 115 .. code-block:: text 116 117 git show b10859ec41d09c57663a258f43fe57c12332698e 118 119 commit b10859ec41d09c57663a258f43fe57c12332698e 120 Author: Jonas Pfeil <pfeiljonas@gmx.de> 121 Date: Wed Mar 1 18:11:10 2017 +0100 122 123 ralloc: Make sure ralloc() allocations match malloc()'s alignment. 124 125 The header of ralloc needs to be aligned, because the compiler assumes 126 ... 127 128 (cherry picked from commit cd2b55e536dc806f9358f71db438dd9c246cdb14) 129 130 Squashed with commit: 131 132 ralloc: don't leave out the alignment factor 133 134 Experimentation shows that without alignment factor GCC and Clang choose 135 ... 136 137 (cherry picked from commit ff494fe999510ea40e3ed5827e7818550b6de126) 138 139Regression/functionality testing 140-------------------------------- 141 142- *no regressions should be observed for Piglit/dEQP/CTS/Vulkan on 143 Intel platforms* 144- *no regressions should be observed for Piglit using the Softpipe 145 and LLVMpipe drivers* 146 147.. _stagingbranch: 148 149Staging branch 150-------------- 151 152A live branch, which contains the currently merge/rejected patches is 153available in the main repository under ``staging/X.Y``. For example: 154 155:: 156 157 staging/18.1 - WIP branch for the 18.1 series 158 staging/18.2 - WIP branch for the 18.2 series 159 160Notes: 161 162- People are encouraged to test the staging branch and report 163 regressions. 164- The branch history is not stable and it **will** be rebased, 165 166Making a branchpoint 167-------------------- 168 169A branchpoint is made such that new development can continue in parallel 170to stabilization and bugfixing. 171 172.. note:: 173 174 Before doing a branch ensure that basic build and ``meson test`` 175 testing is done and there are little to-no issues. Ideally all of those 176 should be tackled already. 177 178Setup the branchpoint: 179 180.. code-block:: sh 181 182 # Make sure main can carry on at the new version 183 $EDITOR VERSION # bump the version number, keeping in mind the wrap around at the end of the year 184 git commit -asm 'VERSION: bump to X.(Y+1)' 185 truncate -s0 docs/relnotes/new_features.txt 186 git commit -asm 'docs: reset new_features.txt' 187 git push YOUR_FORK 188 189Make a merge request with what you just pushed, and assign it straight 190to ``@Marge-bot``. Keep an eye on it, as you'll need to wait for it to 191be merged. 192 193Once it has been merged, note the last commit *before* your "VERSION: 194bump to X.Y" as this is the branchpoint. This is ``$LAST_COMMIT`` in the 195command below: 196 197.. code-block:: sh 198 199 VERSION=X.Y 200 201 git tag -s $VERSION-branchpoint -m "Mesa $VERSION branchpoint" $LAST_COMMIT 202 203 # Double-check that you tagged the correct commit 204 git show $VERSION-branchpoint 205 206Now that we have an official branchpoint, let's push the tag and create 207the branches: 208 209.. code-block:: sh 210 211 git push origin $VERSION-branchpoint 212 git checkout $VERSION-branchpoint 213 git push origin HEAD:refs/heads/$VERSION 214 git push origin HEAD:refs/heads/staging/$VERSION 215 git checkout staging/$VERSION 216 217You are now on the :ref:`staging branch <stagingbranch>`, where you 218will be doing your release maintainer work. This branch can be rebased 219and altered in way necessary, with the caveat that anything pushed to 220the ``X.Y`` branch must not be altered anymore. A convenient command 221to perform an interactive rebase over everything since the last release is: 222 223.. code-block:: sh 224 225 git rebase -i mesa-$(cat VERSION) 226 227Now go to 228`GitLab <https://gitlab.freedesktop.org/mesa/mesa/-/milestones>`__ and 229add the new Mesa version X.Y. 230 231Check that there are no distribution breaking changes and revert them if 232needed. For example: files being overwritten on install, etc. Happens 233extremely rarely - we had only one case so far (see commit 2342ced8eb136528914e1bf4e000dea06a9d53c7e04). 235 236Making a new release 237-------------------- 238 239These are the instructions for making a new Mesa release. 240 241Get latest source files 242~~~~~~~~~~~~~~~~~~~~~~~ 243 244Ensure the latest code is available - both in your local main and the 245relevant branch. 246 247Perform basic testing 248~~~~~~~~~~~~~~~~~~~~~ 249 250Most of the testing should already be done during the 251:ref:`cherry-pick <pickntest>` So we do a quick 'touch test' 252 253- meson dist 254- the produced binaries work 255 256Here is one solution: 257 258.. code-block:: sh 259 260 __glxgears_cmd='glxgears 2>&1 | grep -v "configuration file"' 261 __es2info_cmd='es2_info 2>&1 | egrep "GL_VERSION|GL_RENDERER|.*dri\.so"' 262 __es2gears_cmd='es2gears_x11 2>&1 | grep -v "configuration file"' 263 test "x$LD_LIBRARY_PATH" != 'x' && __old_ld="$LD_LIBRARY_PATH" 264 export LD_LIBRARY_PATH=`pwd`/test/usr/local/lib/:"${__old_ld}" 265 export LIBGL_DRIVERS_PATH=`pwd`/test/usr/local/lib/dri/ 266 export LIBGL_DEBUG=verbose 267 eval $__glxinfo_cmd 268 eval $__glxgears_cmd 269 eval $__es2info_cmd 270 eval $__es2gears_cmd 271 export LIBGL_ALWAYS_SOFTWARE=true 272 eval $__glxinfo_cmd 273 eval $__glxgears_cmd 274 eval $__es2info_cmd 275 eval $__es2gears_cmd 276 export LIBGL_ALWAYS_SOFTWARE=true 277 export GALLIUM_DRIVER=softpipe 278 eval $__glxinfo_cmd 279 eval $__glxgears_cmd 280 eval $__es2info_cmd 281 eval $__es2gears_cmd 282 # Smoke test DOTA2 283 unset LD_LIBRARY_PATH 284 test "x$__old_ld" != 'x' && export LD_LIBRARY_PATH="$__old_ld" && unset __old_ld 285 unset LIBGL_DRIVERS_PATH 286 unset LIBGL_DEBUG 287 unset LIBGL_ALWAYS_SOFTWARE 288 unset GALLIUM_DRIVER 289 export VK_ICD_FILENAMES=`pwd`/test/usr/local/share/vulkan/icd.d/intel_icd.x86_64.json 290 steam steam://rungameid/570 -vconsole -vulkan 291 unset VK_ICD_FILENAMES 292 293Create release notes for the new release 294~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 295 296The release notes are completely generated by the 297``bin/gen_release_notes.py`` script. Simply run this script **before** 298bumping the version. You'll need to come back to this file once the 299tarball is generated to add its SHA256 checksum. 300 301Increment the version contained in the file ``VERSION`` at Mesa's top-level, 302then commit this change and **push the branch** (if you forget to do 303this, ``release.sh`` below will fail). 304 305Use the release.sh script from X.Org `util-modular <https://gitlab.freedesktop.org/xorg/util/modular>`__ 306~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 307 308Start the release process. 309 310.. code-block:: sh 311 312 ../relative/path/to/release.sh . # append --dist if you've already done distcheck above 313 314Pay close attention to the prompts as you might be required to enter 315your GPG and SSH passphrase(s) to sign and upload the files, 316respectively. 317 318Ensure that you do sign the tarballs, that your key is mentioned in the 319release notes, and is published in `release-maintainers-keys.asc 320<release-maintainers-keys.asc>`__. 321 322 323Add the SHA256 checksums to the release notes 324~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 325 326Edit ``docs/relnotes/X.Y.Z.rst`` to add the SHA256 checksums as available 327in the ``mesa-X.Y.Z.announce`` template. Commit this change. 328 329Don't forget to push the commits to both the ``staging/X.Y`` branch and 330the ``X.Y`` branch: 331 332.. code-block:: sh 333 334 git push origin HEAD:staging/X.Y 335 git push origin HEAD:X.Y 336 337 338Back on mesa main, add the new release notes into the tree 339~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 340 341Something like the following steps will do the trick: 342 343.. code-block:: sh 344 345 git cherry-pick -x X.Y~1 346 git cherry-pick -x X.Y 347 348Then run the 349 350.. code-block:: sh 351 352 ./bin/post_version.py X.Y.Z 353 354, where X.Y.Z is the version you just made. This will update 355docs/relnotes.rst and docs/release-calendar.csv. It will then generate 356a Git commit automatically. Check that everything looks correct and 357push: 358 359.. code-block:: sh 360 361 git push origin main X.Y 362 363Announce the release 364-------------------- 365 366Use the generated template during the releasing process. 367 368Again, pay attention to add a note to warn about a final release in a 369series, if that is the case. 370 371Update GitLab issues 372-------------------- 373 374Parse through the bug reports as listed in the docs/relnotes/X.Y.Z.rst 375document. If there's outstanding action, close the bug referencing the 376commit ID which addresses the bug and mention the Mesa version that has 377the fix. 378 379.. note: the above is not applicable to all the reports, so use common sense. 380