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:: console 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 swrast, 145 softpipe 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 178Check if the version number is going to remain as, alternatively 179``git mv docs/relnotes/{current,new}.rst`` as appropriate. 180 181To setup the branchpoint: 182 183.. code-block:: console 184 185 git checkout main # make sure we're in main first 186 git tag -s X.Y-branchpoint -m "Mesa X.Y branchpoint" 187 git checkout -b X.Y 188 git checkout main 189 $EDITOR VERSION # bump the version number 190 git commit -as 191 truncate docs/relnotes/new_features.txt 192 git commit -a 193 git push origin X.Y-branchpoint X.Y 194 195Now go to 196`GitLab <https://gitlab.freedesktop.org/mesa/mesa/-/milestones>`__ and 197add the new Mesa version X.Y. 198 199Check that there are no distribution breaking changes and revert them if 200needed. For example: files being overwritten on install, etc. Happens 201extremely rarely - we had only one case so far (see commit 2022ced8eb136528914e1bf4e000dea06a9d53c7e04). 203 204Making a new release 205-------------------- 206 207These are the instructions for making a new Mesa release. 208 209Get latest source files 210~~~~~~~~~~~~~~~~~~~~~~~ 211 212Ensure the latest code is available - both in your local main and the 213relevant branch. 214 215Perform basic testing 216~~~~~~~~~~~~~~~~~~~~~ 217 218Most of the testing should already be done during the 219:ref:`cherry-pick <pickntest>` So we do a quick 'touch test' 220 221- meson dist 222- the produced binaries work 223 224Here is one solution: 225 226.. code-block:: console 227 228 __glxgears_cmd='glxgears 2>&1 | grep -v "configuration file"' 229 __es2info_cmd='es2_info 2>&1 | egrep "GL_VERSION|GL_RENDERER|.*dri\.so"' 230 __es2gears_cmd='es2gears_x11 2>&1 | grep -v "configuration file"' 231 test "x$LD_LIBRARY_PATH" != 'x' && __old_ld="$LD_LIBRARY_PATH" 232 export LD_LIBRARY_PATH=`pwd`/test/usr/local/lib/:"${__old_ld}" 233 export LIBGL_DRIVERS_PATH=`pwd`/test/usr/local/lib/dri/ 234 export LIBGL_DEBUG=verbose 235 eval $__glxinfo_cmd 236 eval $__glxgears_cmd 237 eval $__es2info_cmd 238 eval $__es2gears_cmd 239 export LIBGL_ALWAYS_SOFTWARE=true 240 eval $__glxinfo_cmd 241 eval $__glxgears_cmd 242 eval $__es2info_cmd 243 eval $__es2gears_cmd 244 export LIBGL_ALWAYS_SOFTWARE=true 245 export GALLIUM_DRIVER=softpipe 246 eval $__glxinfo_cmd 247 eval $__glxgears_cmd 248 eval $__es2info_cmd 249 eval $__es2gears_cmd 250 # Smoke test DOTA2 251 unset LD_LIBRARY_PATH 252 test "x$__old_ld" != 'x' && export LD_LIBRARY_PATH="$__old_ld" && unset __old_ld 253 unset LIBGL_DRIVERS_PATH 254 unset LIBGL_DEBUG 255 unset LIBGL_ALWAYS_SOFTWARE 256 unset GALLIUM_DRIVER 257 export VK_ICD_FILENAMES=`pwd`/test/usr/local/share/vulkan/icd.d/intel_icd.x86_64.json 258 steam steam://rungameid/570 -vconsole -vulkan 259 unset VK_ICD_FILENAMES 260 261Create release notes for the new release 262~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 263 264The release notes are completely generated by the 265``bin/gen_release_notes.py`` script. Simply run this script **before** 266bumping the version. You'll need to come back to this file once the 267tarball is generated to add its ``sha256sum``. 268 269Increment the version contained in the file ``VERSION`` at Mesa's top-level, 270then commit this change and **push the branch** (if you forget to do 271this, ``release.sh`` below will fail). 272 273Use the release.sh script from xorg `util-modular <https://cgit.freedesktop.org/xorg/util/modular/>`__ 274~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 275 276Start the release process. 277 278.. code-block:: console 279 280 ../relative/path/to/release.sh . # append --dist if you've already done distcheck above 281 282Pay close attention to the prompts as you might be required to enter 283your GPG and SSH passphrase(s) to sign and upload the files, 284respectively. 285 286Ensure that you do sign the tarballs, that your key is mentioned in the 287release notes, and is published in `release-maintainers-keys.asc 288<release-maintainers-keys.asc>`__. 289 290 291Add the sha256sums to the release notes 292~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 293 294Edit ``docs/relnotes/X.Y.Z.rst`` to add the ``sha256sum`` as available in the 295``mesa-X.Y.Z.announce`` template. Commit this change. 296 297Back on mesa main, add the new release notes into the tree 298~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 299 300Something like the following steps will do the trick: 301 302.. code-block:: console 303 304 git cherry-pick -x X.Y~1 305 git cherry-pick -x X.Y 306 307Then run the 308 309.. code-block:: console 310 311 ./bin/post_version.py X.Y.Z 312 313, where X.Y.Z is the version you just made. This will update 314docs/relnotes.rst and docs/release-calendar.csv. It will then generate 315a Git commit automatically. Check that everything looks correct and 316push: 317 318.. code-block:: console 319 320 git push origin main X.Y 321 322Announce the release 323-------------------- 324 325Use the generated template during the releasing process. 326 327Again, pay attention to add a note to warn about a final release in a 328series, if that is the case. 329 330Update GitLab issues 331-------------------- 332 333Parse through the bug reports as listed in the docs/relnotes/X.Y.Z.rst 334document. If there's outstanding action, close the bug referencing the 335commit ID which addresses the bug and mention the Mesa version that has 336the fix. 337 338.. note: the above is not applicable to all the reports, so use common sense. 339