docs/releasing.rst

   1 Releasing Process
   2 =================
   3
   4 Overview
   5 --------
   6
   7 This document uses the convention X.Y.Z for the release number with X.Y
   8 being the stable branch name.
   9
  10 Mesa provides feature and bugfix releases. Former use zero as patch
  11 version (Z), while the latter have a non-zero one.
  12
  13 For 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
  24 Release schedule
  25 ----------------
  26
  27 Releases should happen on Wednesdays. Delays can occur although those
  28 should be kept to a minimum.
  29
  30 See our :doc:`calendar <release-calendar>` for information about how
  31 the release schedule is planned, and the date and other details for
  32 individual releases.
  33
  34 Feature 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
  46 Stable 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
  68 Cherry-picking and testing
  69 --------------------------
  70
  71 Commits nominated for the active branch are picked as based on the
  72 :ref:`criteria <criteria>` as described in the same
  73 section.
  74
  75 Nominations happen via special tags in the commit messages, and via
  76 GitLab merge requests against the staging branches. There are special
  77 scripts used to read the tags.
  78
  79 The maintainer should watch or be in contact with the Intel CI team, as
  80 well as watch the GitLab CI for regressions.
  81
  82 Cherry 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
  87 Developers can request, *as an exception*, patches to be applied up-to
  88 the last one hour before the actual release. This is made **only** with
  89 explicit permission/request, and the patch **must** be very well
  90 contained. Thus it cannot affect more than one driver/subsystem.
  91
  92 Following developers have requested permanent exception
  93
  94 -  *Ilia Mirkin*
  95 -  *AMD team*
  96
  97 The GitLab CI must pass.
  98
  99 For Windows related changes, the main contact point is Brian Paul. Jose
 100 Fonseca can also help as a fallback contact.
 101
 102 For Android related changes, the main contact is Tapani Pälli. Mauro
 103 Rossi is collaborating with Android-x86 and may provide feedback about
 104 the build status in that project.
 105
 106 For MacOSX related changes, Jeremy Huddleston Sequoia is currently a
 107 good 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
 139 Regression/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
 149 Staging branch
 150 --------------
 151
 152 A live branch, which contains the currently merge/rejected patches is
 153 available 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
 160 Notes:
 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
 166 Making a branchpoint
 167 --------------------
 168
 169 A branchpoint is made such that new development can continue in parallel
 170 to 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
 178 To 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
 200 Now go to
 201 `GitLab <https://gitlab.freedesktop.org/mesa/mesa/-/milestones>`__ and
 202 add the new Mesa version X.Y.
 203
 204 Check that there are no distribution breaking changes and revert them if
 205 needed. For example: files being overwritten on install, etc. Happens
 206 extremely rarely - we had only one case so far (see commit
 207 2ced8eb136528914e1bf4e000dea06a9d53c7e04).
 208
 209 Making a new release
 210 --------------------
 211
 212 These are the instructions for making a new Mesa release.
 213
 214 Get latest source files
 215 ~~~~~~~~~~~~~~~~~~~~~~~
 216
 217 Ensure the latest code is available - both in your local main and the
 218 relevant branch.
 219
 220 Perform basic testing
 221 ~~~~~~~~~~~~~~~~~~~~~
 222
 223 Most 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
 229 Here 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
 266 Create release notes for the new release
 267 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 268
 269 The release notes are completely generated by the
 270 ``bin/gen_release_notes.py`` script. Simply run this script **before**
 271 bumping the version. You'll need to come back to this file once the
 272 tarball is generated to add its SHA256 checksum.
 273
 274 Increment the version contained in the file ``VERSION`` at Mesa's top-level,
 275 then commit this change and **push the branch** (if you forget to do
 276 this, ``release.sh`` below will fail).
 277
 278 Use the release.sh script from X.Org `util-modular <https://gitlab.freedesktop.org/xorg/util/modular>`__
 279 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 280
 281 Start 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
 287 Pay close attention to the prompts as you might be required to enter
 288 your GPG and SSH passphrase(s) to sign and upload the files,
 289 respectively.
 290
 291 Ensure that you do sign the tarballs, that your key is mentioned in the
 292 release notes, and is published in `release-maintainers-keys.asc
 293 <release-maintainers-keys.asc>`__.
 294
 295
 296 Add the SHA256 checksums to the release notes
 297 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 298
 299 Edit ``docs/relnotes/X.Y.Z.rst`` to add the SHA256 checksums as available
 300 in the ``mesa-X.Y.Z.announce`` template. Commit this change.
 301
 302 Don't forget to push the commits to both the ``staging/X.Y`` branch and
 303 the ``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
 311 Back on mesa main, add the new release notes into the tree
 312 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 313
 314 Something 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
 321 Then 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
 328 docs/relnotes.rst and docs/release-calendar.csv. It will then generate
 329 a Git commit automatically. Check that everything looks correct and
 330 push:
 331
 332 .. code-block:: console
 333
 334       git push origin main X.Y
 335
 336 Announce the release
 337 --------------------
 338
 339 Use the generated template during the releasing process.
 340
 341 Again, pay attention to add a note to warn about a final release in a
 342 series, if that is the case.
 343
 344 Update GitLab issues
 345 --------------------
 346
 347 Parse through the bug reports as listed in the docs/relnotes/X.Y.Z.rst
 348 document. If there's outstanding action, close the bug referencing the
 349 commit ID which addresses the bug and mention the Mesa version that has
 350 the fix.
 351
 352 .. note: the above is not applicable to all the reports, so use common sense.