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