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:: 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:: 184 185 git checkout master # make sure we're in master first 186 git tag -s X.Y-branchpoint -m "Mesa X.Y branchpoint" 187 git checkout -b X.Y 188 git checkout master 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 master 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- scons (from release tarball) 223- the produced binaries work 224 225Here is one solution: 226 227:: 228 229 __glxgears_cmd='glxgears 2>&1 | grep -v "configuration file"' 230 __es2info_cmd='es2_info 2>&1 | egrep "GL_VERSION|GL_RENDERER|.*dri\.so"' 231 __es2gears_cmd='es2gears_x11 2>&1 | grep -v "configuration file"' 232 test "x$LD_LIBRARY_PATH" != 'x' && __old_ld="$LD_LIBRARY_PATH" 233 export LD_LIBRARY_PATH=`pwd`/test/usr/local/lib/:"${__old_ld}" 234 export LIBGL_DRIVERS_PATH=`pwd`/test/usr/local/lib/dri/ 235 export LIBGL_DEBUG=verbose 236 eval $__glxinfo_cmd 237 eval $__glxgears_cmd 238 eval $__es2info_cmd 239 eval $__es2gears_cmd 240 export LIBGL_ALWAYS_SOFTWARE=true 241 eval $__glxinfo_cmd 242 eval $__glxgears_cmd 243 eval $__es2info_cmd 244 eval $__es2gears_cmd 245 export LIBGL_ALWAYS_SOFTWARE=true 246 export GALLIUM_DRIVER=softpipe 247 eval $__glxinfo_cmd 248 eval $__glxgears_cmd 249 eval $__es2info_cmd 250 eval $__es2gears_cmd 251 # Smoke test DOTA2 252 unset LD_LIBRARY_PATH 253 test "x$__old_ld" != 'x' && export LD_LIBRARY_PATH="$__old_ld" && unset __old_ld 254 unset LIBGL_DRIVERS_PATH 255 unset LIBGL_DEBUG 256 unset LIBGL_ALWAYS_SOFTWARE 257 unset GALLIUM_DRIVER 258 export VK_ICD_FILENAMES=`pwd`/test/usr/local/share/vulkan/icd.d/intel_icd.x86_64.json 259 steam steam://rungameid/570 -vconsole -vulkan 260 unset VK_ICD_FILENAMES 261 262Create release notes for the new release 263~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 264 265The release notes are completely generated by the 266``bin/gen_release_notes.py`` script. Simply run this script **before** 267bumping the version. You'll need to come back to this file once the 268tarball is generated to add its ``sha256sum``. 269 270Increment the version contained in the file ``VERSION`` at Mesa's top-level, 271then commit this change and **push the branch** (if you forget to do 272this, ``release.sh`` below will fail). 273 274Use the release.sh script from xorg `util-modular <https://cgit.freedesktop.org/xorg/util/modular/>`__ 275~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 276 277Start the release process. 278 279:: 280 281 ../relative/path/to/release.sh . # append --dist if you've already done distcheck above 282 283Pay close attention to the prompts as you might be required to enter 284your GPG and SSH passphrase(s) to sign and upload the files, 285respectively. 286 287Ensure that you do sign the tarballs, that your key is mentioned in the 288release notes, and is published in `release-maintainers-keys.asc 289<release-maintainers-keys.asc>`__. 290 291 292Add the sha256sums to the release notes 293~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 294 295Edit ``docs/relnotes/X.Y.Z.rst`` to add the ``sha256sum`` as available in the 296``mesa-X.Y.Z.announce`` template. Commit this change. 297 298Back on mesa master, add the new release notes into the tree 299~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 300 301Something like the following steps will do the trick: 302 303:: 304 305 git cherry-pick -x X.Y~1 306 git cherry-pick -x X.Y 307 308Then run the 309 310:: 311 312 ./bin/post_version.py X.Y.Z 313 314, where X.Y.Z is the version you just made. This will update 315docs/relnotes.rst and docs/release-calendar.rst. It will then generate 316a Git commit automatically. Check that everything looks correct and 317push: 318 319:: 320 321 git push origin master X.Y 322 323Announce the release 324-------------------- 325 326Use the generated template during the releasing process. 327 328Again, pay attention to add a note to warn about a final release in a 329series, if that is the case. 330 331Update GitLab issues 332-------------------- 333 334Parse through the bug reports as listed in the docs/relnotes/X.Y.Z.rst 335document. If there's outstanding action, close the bug referencing the 336commit ID which addresses the bug and mention the Mesa version that has 337the fix. 338 339.. note: the above is not applicable to all the reports, so use common sense. 340