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