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 -  Initial timeplan available 2-4 weeks before the planned branchpoint
  39    (rc1) on the mesa-announce@ mailing list.
  40 -  Typically, the final release will happen after 4 candidates.
  41    Additional ones may be needed in order to resolve blocking
  42    regressions, though.
  43
  44 Stable releases
  45 ---------------
  46
  47 -  Normally available once every two weeks.
  48 -  Only the latest branch has releases. See note below.
  49
  50 .. note::
  51
  52    There is one or two releases overlap when changing branches. For
  53    example:
  54
  55    The final release from the 12.0 series Mesa 12.0.5 will be out around
  56    the same time (or shortly after) 13.0.1 is out.
  57
  58    This also involves that, as a final release may be delayed due to the
  59    need of additional candidates to solve some blocking regression(s), the
  60    release manager might have to update the
  61    :doc:`calendar <release-calendar>` with additional bug fix releases of
  62    the current stable branch.
  63
  64 .. _pickntest:
  65
  66 Cherry-picking and testing
  67 --------------------------
  68
  69 Commits nominated for the active branch are picked as based on the
  70 :ref:`criteria <criteria>` as described in the same
  71 section.
  72
  73 Nominations happen via special tags in the commit messages, and via
  74 gitlab merge requests against the staging branches. There are special
  75 scripts used to read the tags.
  76
  77 The maintainer should watch or be in contact with the Intel CI team, as
  78 well as watch the gitlab CI for regressions.
  79
  80 Cherry picking should be done with the '-x' switch (to automatically add
  81 "cherry picked from ..." to the commit message):
  82
  83 ``git cherry-pick -x abcdef12345667890``
  84
  85 Developers can request, *as an exception*, patches to be applied up-to
  86 the last one hour before the actual release. This is made **only** with
  87 explicit permission/request, and the patch **must** be very well
  88 contained. Thus it cannot affect more than one driver/subsystem.
  89
  90 Following developers have requested permanent exception
  91
  92 -  *Ilia Mirkin*
  93 -  *AMD team*
  94
  95 The gitlab CI must pass.
  96
  97 For Windows related changes, the main contact point is Brian Paul. Jose
  98 Fonseca can also help as a fallback contact.
  99
 100 For Android related changes, the main contact is Tapani Pälli. Mauro
 101 Rossi is collaborating with android-x86 and may provide feedback about
 102 the build status in that project.
 103
 104 For MacOSX related changes, Jeremy Huddleston Sequoia is currently a
 105 good contact point.
 106
 107 .. note::
 108
 109    If a patch in the current queue needs any additional fix(es),
 110    then they should be squashed together. The commit messages and the
 111    "``cherry picked from``"-tags must be preserved.
 112
 113 ::
 114
 115    git show b10859ec41d09c57663a258f43fe57c12332698e
 116
 117    commit b10859ec41d09c57663a258f43fe57c12332698e
 118    Author: Jonas Pfeil <pfeiljonas@gmx.de>
 119    Date:   Wed Mar 1 18:11:10 2017 +0100
 120
 121        ralloc: Make sure ralloc() allocations match malloc()'s alignment.
 122
 123        The header of ralloc needs to be aligned, because the compiler assumes
 124        ...
 125
 126        (cherry picked from commit cd2b55e536dc806f9358f71db438dd9c246cdb14)
 127
 128        Squashed with commit:
 129
 130        ralloc: don't leave out the alignment factor
 131
 132        Experimentation shows that without alignment factor gcc and clang choose
 133        ...
 134
 135        (cherry picked from commit ff494fe999510ea40e3ed5827e7818550b6de126)
 136
 137 Regression/functionality testing
 138 --------------------------------
 139
 140 -  *no regressions should be observed for Piglit/dEQP/CTS/Vulkan on
 141    Intel platforms*
 142 -  *no regressions should be observed for Piglit using the swrast,
 143    softpipe and llvmpipe drivers*
 144
 145 .. _stagingbranch:
 146
 147 Staging branch
 148 --------------
 149
 150 A live branch, which contains the currently merge/rejected patches is
 151 available in the main repository under ``staging/X.Y``. For example:
 152
 153 ::
 154
 155    staging/18.1 - WIP branch for the 18.1 series
 156    staging/18.2 - WIP branch for the 18.2 series
 157
 158 Notes:
 159
 160 -  People are encouraged to test the staging branch and report
 161    regressions.
 162 -  The branch history is not stable and it **will** be rebased,
 163
 164 Making a branchpoint
 165 --------------------
 166
 167 A branchpoint is made such that new development can continue in parallel
 168 to stabilisation and bugfixing.
 169
 170 .. note::
 171
 172    Before doing a branch ensure that basic build and ``meson test``
 173    testing is done and there are little to-no issues. Ideally all of those
 174    should be tackled already.
 175
 176 Check if the version number is going to remain as, alternatively
 177 ``git mv docs/relnotes/{current,new}.rst`` as appropriate.
 178
 179 To setup the branchpoint:
 180
 181 ::
 182
 183    git checkout master # make sure we're in master first
 184    git tag -s X.Y-branchpoint -m "Mesa X.Y branchpoint"
 185    git checkout -b X.Y
 186    git checkout master
 187    $EDITOR VERSION # bump the version number
 188    git commit -as
 189    truncate docs/relnotes/new_features.txt
 190    git commit -a
 191    git push origin X.Y-branchpoint X.Y
 192
 193 Now go to
 194 `gitlab <https://gitlab.freedesktop.org/mesa/mesa/-/milestones>`__ and
 195 add the new Mesa version X.Y.
 196
 197 Check that there are no distribution breaking changes and revert them if
 198 needed. For example: files being overwritten on install, etc. Happens
 199 extremely rarely - we had only one case so far (see commit
 200 2ced8eb136528914e1bf4e000dea06a9d53c7e04).
 201
 202 Making a new release
 203 --------------------
 204
 205 These are the instructions for making a new Mesa release.
 206
 207 Get latest source files
 208 ~~~~~~~~~~~~~~~~~~~~~~~
 209
 210 Ensure the latest code is available - both in your local master and the
 211 relevant branch.
 212
 213 Perform basic testing
 214 ~~~~~~~~~~~~~~~~~~~~~
 215
 216 Most of the testing should already be done during the
 217 :ref:`cherry-pick <pickntest>` So we do a quick 'touch test'
 218
 219 -  meson dist
 220 -  scons (from release tarball)
 221 -  the produced binaries work
 222
 223 Here is one solution:
 224
 225 ::
 226
 227    __glxgears_cmd='glxgears 2>&1 | grep -v "configuration file"'
 228    __es2info_cmd='es2_info 2>&1 | egrep "GL_VERSION|GL_RENDERER|.*dri\.so"'
 229    __es2gears_cmd='es2gears_x11 2>&1 | grep -v "configuration file"'
 230    test "x$LD_LIBRARY_PATH" != 'x' && __old_ld="$LD_LIBRARY_PATH"
 231    export LD_LIBRARY_PATH=`pwd`/test/usr/local/lib/:"${__old_ld}"
 232    export LIBGL_DRIVERS_PATH=`pwd`/test/usr/local/lib/dri/
 233    export LIBGL_DEBUG=verbose
 234    eval $__glxinfo_cmd
 235    eval $__glxgears_cmd
 236    eval $__es2info_cmd
 237    eval $__es2gears_cmd
 238    export LIBGL_ALWAYS_SOFTWARE=true
 239    eval $__glxinfo_cmd
 240    eval $__glxgears_cmd
 241    eval $__es2info_cmd
 242    eval $__es2gears_cmd
 243    export LIBGL_ALWAYS_SOFTWARE=true
 244    export GALLIUM_DRIVER=softpipe
 245    eval $__glxinfo_cmd
 246    eval $__glxgears_cmd
 247    eval $__es2info_cmd
 248    eval $__es2gears_cmd
 249    # Smoke test DOTA2
 250    unset LD_LIBRARY_PATH
 251    test "x$__old_ld" != 'x' && export LD_LIBRARY_PATH="$__old_ld" && unset __old_ld
 252    unset LIBGL_DRIVERS_PATH
 253    unset LIBGL_DEBUG
 254    unset LIBGL_ALWAYS_SOFTWARE
 255    unset GALLIUM_DRIVER
 256    export VK_ICD_FILENAMES=`pwd`/test/usr/local/share/vulkan/icd.d/intel_icd.x86_64.json
 257    steam steam://rungameid/570  -vconsole -vulkan
 258    unset VK_ICD_FILENAMES
 259
 260 Create release notes for the new release
 261 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 262
 263 The release notes are completely generated by the
 264 ``bin/gen_release_notes.py`` script. Simply run this script **before**
 265 bumping the version. You'll need to come back to this file once the
 266 tarball is generated to add its ``sha256sum``.
 267
 268 Increment the version contained in the file ``VERSION`` at Mesa's top-level,
 269 then commit this change and **push the branch** (if you forget to do
 270 this, ``release.sh`` below will fail).
 271
 272 Use the release.sh script from xorg `util-modular <https://cgit.freedesktop.org/xorg/util/modular/>`__
 273 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 274
 275 Start the release process.
 276
 277 ::
 278
 279    ../relative/path/to/release.sh . # append --dist if you've already done distcheck above
 280
 281 Pay close attention to the prompts as you might be required to enter
 282 your GPG and SSH passphrase(s) to sign and upload the files,
 283 respectively.
 284
 285 Ensure that you do sign the tarballs, that your key is mentioned in the
 286 release notes, and is published in `release-maintainers-keys.asc
 287 <release-maintainers-keys.asc>`__.
 288
 289
 290 Add the sha256sums to the release notes
 291 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 292
 293 Edit ``docs/relnotes/X.Y.Z.rst`` to add the ``sha256sum`` as available in the
 294 ``mesa-X.Y.Z.announce`` template. Commit this change.
 295
 296 Back on mesa master, add the new release notes into the tree
 297 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 298
 299 Something like the following steps will do the trick:
 300
 301 ::
 302
 303    git cherry-pick -x X.Y~1
 304    git cherry-pick -x X.Y
 305
 306 Then run the
 307
 308 ::
 309
 310    ./bin/post_version.py X.Y.Z
 311
 312 , where X.Y.Z is the version you just made. This will update
 313 docs/relnotes.rst and docs/release-calendar.rst. It will then generate
 314 a git commit automatically. Check that everything looks correct and
 315 push:
 316
 317 ::
 318
 319       git push origin master X.Y
 320
 321 Announce the release
 322 --------------------
 323
 324 Use the generated template during the releasing process.
 325
 326 Again, pay attention to add a note to warn about a final release in a
 327 series, if that is the case.
 328
 329 Update gitlab issues
 330 --------------------
 331
 332 Parse through the bug reports as listed in the docs/relnotes/X.Y.Z.rst
 333 document. If there's outstanding action, close the bug referencing the
 334 commit ID which addresses the bug and mention the Mesa version that has
 335 the fix.
 336
 337 .. note: the above is not applicable to all the reports, so use common sense.