docs/releasing.html

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