docs/releasing.rst

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