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="#prerelease">Pre-release announcement</a>
  27 <li><a href="#release">Making a new release</a>
  28 <li><a href="#announce">Announce the release</a>
  29 <li><a href="#gitlab">Update Gitlab Issues</a>
  30 </ul>
  31
  32
  33 <h2 id="overview">Overview</h2>
  34
  35 <p>
  36 This document uses the convention X.Y.Z for the release number with X.Y being
  37 the stable branch name.
  38 </p>
  39
  40 <p>
  41 Mesa provides feature and bugfix releases. Former use zero as patch version (Z),
  42 while the latter have a non-zero one.
  43 </p>
  44
  45 <p>
  46 For example:
  47 </p>
  48 <pre>
  49         Mesa 10.1.0 - 10.1 branch, feature
  50         Mesa 10.1.4 - 10.1 branch, bugfix
  51         Mesa 12.0.0 - 12.0 branch, feature
  52         Mesa 12.0.2 - 12.0 branch, bugfix
  53 </pre>
  54
  55
  56 <h2 id="schedule">Release schedule</h2>
  57
  58 <p>
  59 Releases should happen on Wednesdays. Delays can occur although those
  60 should be kept to a minimum.
  61 </p>
  62
  63 <p>
  64 See our <a href="release-calendar.html" target="_parent">calendar</a>
  65 for information about how the release schedule is planned, and the
  66 date and other details for individual releases.
  67 </p>
  68
  69 <h2>Feature releases</h2>
  70 <ul>
  71 <li>Available approximately every three months.
  72 <li>Initial timeplan available 2-4 weeks before the planned branchpoint (rc1)
  73 on the mesa-announce@ mailing list.
  74 <li>Typically, the final release will happen after 4
  75 candidates. Additional ones may be needed in order to resolve blocking
  76 regressions, though.
  77 <li>A <a href="#prerelease">pre-release</a> announcement should be available
  78 approximately 24 hours before the final (non-rc) release.
  79 </ul>
  80
  81 <h2>Stable releases</h2>
  82 <ul>
  83 <li>Normally available once every two weeks.
  84 <li>Only the latest branch has releases. See note below.
  85 <li>A <a href="#prerelease">pre-release</a> announcement should be available
  86 approximately 48 hours before the actual release.
  87 </ul>
  88
  89 <p>
  90 Note: There is one or two releases overlap when changing branches. For example:
  91 </p>
  92
  93 <p>
  94 The final release from the 12.0 series Mesa 12.0.5 will be out around the same
  95 time (or shortly after) 13.0.1 is out.
  96 </p>
  97
  98 <p>
  99 This also involves that, as a final release may be delayed due to the
 100 need of additional candidates to solve some blocking regression(s),
 101 the release manager might have to update
 102 the <a href="release-calendar.html" target="_parent">calendar</a> with
 103 additional bug fix releases of the current stable branch.
 104 </p>
 105
 106
 107 <h2 id="pickntest">Cherry-picking and testing</h2>
 108
 109 <p>
 110 Commits nominated for the active branch are picked as based on the
 111 <a href="submittingpatches.html#criteria" target="_parent">criteria</a> as
 112 described in the same section.
 113 </p>
 114
 115 <p>
 116 Nomination happens in the mesa-stable@ mailing list. However,
 117 maintainer is responsible of checking for forgotten candidates in the
 118 master branch. This is achieved by a combination of ad-hoc scripts and
 119 a casual search for terms such as regression, fix, broken and similar.
 120 </p>
 121
 122 <p>
 123 Maintainer is also responsible for testing in various possible permutations of
 124 the meson and scons build.
 125 </p>
 126
 127 <h2>Cherry-picking and build/check testing</h2>
 128
 129 <p>Done continuously up-to the <a href="#prerelease">pre-release</a> announcement.</p>
 130
 131 <p>
 132 Developers can request, <em>as an exception</em>, patches to be applied up-to
 133 the last one hour before the actual release. This is made <strong>only</strong>
 134 with explicit permission/request, and the patch <strong>must</strong> be very
 135 well contained. Thus it cannot affect more than one driver/subsystem.
 136 </p>
 137
 138 <p>Following developers have requested permanent exception</p>
 139 <ul>
 140 <li><em>Ilia Mirkin</em>
 141 <li><em>AMD team</em>
 142 </ul>
 143
 144 <p>The following must pass:</p>
 145 <ul>
 146 <li>meson test, scons and scons check
 147 <li>Testing with different version of system components - LLVM and others is also
 148 performed where possible.
 149 <li>As a general rule, testing with various combinations of configure
 150 switches, depending on the specific patchset.
 151 </ul>
 152
 153 <p>
 154 These are achieved by combination of <a href="basictesting">local testing</a>,
 155 which includes mingw-w64 cross compilation and AppVeyor plus Travis-CI, the
 156 latter two as part of their Github integration.
 157 </p>
 158
 159 <p>
 160 For Windows related changes, the main contact point is Brian
 161 Paul. Jose Fonseca can also help as a fallback contact.
 162 </p>
 163
 164 <p>
 165 For Android related changes, the main contact is Tapani
 166 P&auml;lli. Mauro Rossi is collaborating with android-x86 and may
 167 provide feedback about the build status in that project.
 168 </p>
 169
 170 <p>
 171 For MacOSX related changes, Jeremy Huddleston Sequoia is currently a
 172 good contact point.
 173 </p>
 174
 175 <p>
 176 <strong>Note:</strong> If a patch in the current queue needs any additional
 177 fix(es), then they should be squashed together. The commit messages and the
 178 &quot;<code>cherry picked from</code>&quot;-tags must be preserved.
 179 </p>
 180
 181 <p>
 182 This should be noted in the <a href="#prerelease">pre-announce</a> email.
 183 </p>
 184
 185 <pre>
 186     git show b10859ec41d09c57663a258f43fe57c12332698e
 187
 188     commit b10859ec41d09c57663a258f43fe57c12332698e
 189     Author: Jonas Pfeil &lt;pfeiljonas@gmx.de&gt;
 190     Date:   Wed Mar 1 18:11:10 2017 +0100
 191
 192         ralloc: Make sure ralloc() allocations match malloc()'s alignment.
 193
 194         The header of ralloc needs to be aligned, because the compiler assumes
 195         ...
 196
 197         (cherry picked from commit cd2b55e536dc806f9358f71db438dd9c246cdb14)
 198
 199         Squashed with commit:
 200
 201         ralloc: don't leave out the alignment factor
 202
 203         Experimentation shows that without alignment factor gcc and clang choose
 204         ...
 205
 206         (cherry picked from commit ff494fe999510ea40e3ed5827e7818550b6de126)
 207 </pre>
 208
 209 <h2>Regression/functionality testing</h2>
 210
 211 <p>
 212 Less often (once or twice), shortly before the pre-release announcement.
 213 Ensure that testing is redone if Intel devs have requested an exception, as per above.
 214 </p>
 215
 216 <ul>
 217 <li><em>no regressions should be observed for Piglit/dEQP/CTS/Vulkan on Intel platforms</em>
 218 <li><em>no regressions should be observed for Piglit using the swrast, softpipe
 219 and llvmpipe drivers</em>
 220 </ul>
 221
 222 <p>
 223 Currently testing is performed courtesy of the Intel OTC team and their Jenkins CI setup. Check with the Intel team over IRC how to get things setup.
 224 </p>
 225
 226 <p>
 227 Installing the built driver from the pre-announced RC branch in the
 228 system and making some every day's use until the release may be a good
 229 idea too.
 230 </p>
 231
 232 <h2 id="stagingbranch">Staging branch</h2>
 233
 234 <p>
 235 A live branch, which contains the currently merge/rejected patches is available
 236 in the main repository under <code>staging/X.Y</code>. For example:
 237 </p>
 238 <pre>
 239         staging/18.1 - WIP branch for the 18.1 series
 240         staging/18.2 - WIP branch for the 18.2 series
 241 </pre>
 242
 243 <p>
 244 Notes:
 245 </p>
 246 <ul>
 247 <li>People are encouraged to test the staging branch and report regressions.</li>
 248 <li>The branch history is not stable and it <strong>will</strong> be rebased,</li>
 249 </ul>
 250
 251
 252 <h2 id="branch">Making a branchpoint</h2>
 253
 254 <p>
 255 A branchpoint is made such that new development can continue in parallel to
 256 stabilisation and bugfixing.
 257 </p>
 258
 259 <p>
 260 Note: Before doing a branch ensure that basic build and <code>meson test</code>
 261 testing is done and there are little to-no issues. Ideally all of those should
 262 be tackled already.
 263 </p>
 264
 265 <p>
 266 Check if the version number is going to remain as, alternatively
 267 <code> git mv docs/relnotes/{current,new}.html </code> as appropriate.
 268 </p>
 269
 270 <p>
 271 To setup the branchpoint:
 272 </p>
 273 <pre>
 274         git checkout master # make sure we're in master first
 275         git tag -s X.Y-branchpoint -m "Mesa X.Y branchpoint"
 276         git checkout -b X.Y
 277         git checkout master
 278         $EDITOR VERSION # bump the version number
 279         git commit -as
 280         cp docs/relnotes/{X.Y,X.Y+1}.html # copy/create relnotes template
 281         git commit -as
 282         git push origin X.Y-branchpoint X.Y
 283 </pre>
 284
 285 <p>
 286 Now go to
 287 <a href="https://gitlab.freedesktop.org/mesa/mesa/-/milestones" target="_parent">gitlab</a> and add the new Mesa version X.Y.
 288 </p>
 289
 290 <p>
 291 Check that there are no distribution breaking changes and revert them if needed.
 292 For example: files being overwritten on install, etc. Happens extremely rarely -
 293 we had only one case so far (see commit 2ced8eb136528914e1bf4e000dea06a9d53c7e04).
 294 </p>
 295
 296 <p>
 297 Proceed to <a href="#release">release</a> -rc1.
 298 </p>
 299
 300
 301 <h2 id="prerelease">Pre-release announcement</h2>
 302
 303 <p>
 304 It comes shortly after outstanding patches in the respective branch are pushed.
 305 Developers can check, in brief, what's the status of their patches. They,
 306 alongside very early testers, are strongly encouraged to test the branch and
 307 report any regressions.
 308 </p>
 309 <p>
 310 It is followed by a brief period (normally 24 or 48 hours) before the actual
 311 release is made.
 312 </p>
 313
 314 <p>
 315 Be aware to add a note to warn about a final release in a series, if
 316 that is the case.
 317 </p>
 318
 319 <h2>Terminology used</h2>
 320
 321 <ul><li>Nominated</ul>
 322
 323 <p>
 324 Patch that is nominated but yet to to merged in the patch queue/branch.
 325 </p>
 326
 327 <ul><li>Queued</ul>
 328
 329 <p>
 330 Patch is in the queue/branch and will feature in the next release.
 331 Barring reported regressions or objections from developers.
 332 </p>
 333
 334 <ul><li>Rejected</ul>
 335
 336 <p>
 337 Patch does not fit the
 338 <a href="submittingpatches.html#criteria" target="_parent">criteria</a> and
 339 is followed by a brief information. The release maintainer is human so if you
 340 believe you've spotted a mistake do let them know.
 341 </p>
 342
 343 <h2>Format/template</h2>
 344 <pre>
 345 Subject: [ANNOUNCE] Mesa X.Y.Z release candidate
 346 To: mesa-announce@...
 347 Cc: mesa-dev@...
 348
 349 Hello list,
 350
 351 The candidate for the Mesa X.Y.Z is now available. Currently we have:
 352  - NUMBER queued
 353  - NUMBER nominated (outstanding)
 354  - and NUMBER rejected patches
 355
 356 [If applicable:
 357 Note: this is the final anticipated release in the SERIES series. Users are
 358 encouraged to migrate to the NEXT_SERIES series in order to obtain future fixes.]
 359
 360 BRIEF SUMMARY OF CHANGES
 361
 362 Take a look at section "Mesa stable queue" for more information.
 363
 364
 365 Testing reports/general approval
 366 --------------------------------
 367 Any testing reports (or general approval of the state of the branch) will be
 368 greatly appreciated.
 369
 370 The plan is to have X.Y.Z this DAY (DATE), around or shortly after TIME.
 371
 372 If you have any questions or suggestions - be that about the current patch
 373 queue or otherwise, please go ahead.
 374
 375
 376 Trivial merge conflicts
 377 -----------------------
 378 List of commits where manual intervention was required.
 379 Keep the authors in the CC list.
 380
 381 commit SHA
 382 Author: AUTHOR
 383
 384     COMMIT SUMMARY
 385
 386     CHERRY PICKED FROM
 387
 388
 389 For example:
 390
 391 commit 990f395e007c3204639daa34efc3049f350ee819
 392 Author: Emil Velikov &lt;emil.velikov@collabora.com&gt;
 393
 394     anv: automake: cleanup the generated json file during make clean
 395
 396     (cherry picked from commit 8df581520a823564be0ab5af7dbb7d501b1c9670)
 397
 398
 399 Cheers,
 400 Emil
 401
 402
 403 Mesa stable queue
 404 -----------------
 405
 406 Nominated (NUMBER)
 407 ==================
 408
 409 AUTHOR (NUMBER):
 410       SHA     COMMIT SUMMARY
 411
 412 For example:
 413
 414 Dave Airlie (1):
 415       2de85eb radv: fix texturesamples to handle single sample case
 416
 417
 418 Queued (NUMBER)
 419 ===============
 420
 421 AUTHOR (NUMBER):
 422       COMMIT SUMMARY
 423 [If applicable:
 424 Squashed with
 425       COMMIT SUMMARY]
 426
 427 For example:
 428
 429 Jonas Pfeil (1):
 430       ralloc: Make sure ralloc() allocations match malloc()'s alignment.
 431 Squashed with
 432       ralloc: don't leave out the alignment factor
 433
 434
 435 Rejected (NUMBER)
 436 =================
 437
 438 AUTHOR (NUMBER):
 439       SHA     COMMIT SUMMARY
 440
 441 Reason: ...
 442
 443 For example:
 444
 445 Emil Velikov (1)
 446       a39ad18 configure.ac: honour LLVM_LIBDIR when linking against LLVM
 447
 448 Reason: The patch was reverted shortly after it was merged.
 449 </pre>
 450
 451
 452 <h2 id="release">Making a new release</h2>
 453
 454 <p>
 455 These are the instructions for making a new Mesa release.
 456 </p>
 457
 458 <h3>Get latest source files</h3>
 459
 460 <p>
 461 Ensure the latest code is available - both in your local master and the
 462 relevant branch.
 463 </p>
 464
 465 <h3 id="basictesting">Perform basic testing</h3>
 466
 467 <p>
 468 Most of the testing should already be done during the
 469 <a href="#pickntest">cherry-pick</a> and
 470 <a href="#prerelease">pre-announce</a> stages.
 471 So we do a quick 'touch test'
 472 </p>
 473
 474 <ul>
 475 <li>meson dist
 476 <li>scons (from release tarball)
 477 <li>the produced binaries work
 478 </ul>
 479
 480 <p>
 481   Here is one solution:
 482 </p>
 483
 484 <pre>
 485     __glxgears_cmd='glxgears 2&gt;&amp;1 | grep -v "configuration file"'
 486     __es2info_cmd='es2_info 2&gt;&amp;1 | egrep "GL_VERSION|GL_RENDERER|.*dri\.so"'
 487     __es2gears_cmd='es2gears_x11 2&gt;&amp;1 | grep -v "configuration file"'
 488     test "x$LD_LIBRARY_PATH" != 'x' &amp;&amp; __old_ld="$LD_LIBRARY_PATH"
 489     export LD_LIBRARY_PATH=`pwd`/test/usr/local/lib/:"${__old_ld}"
 490     export LIBGL_DRIVERS_PATH=`pwd`/test/usr/local/lib/dri/
 491     export LIBGL_DEBUG=verbose
 492     eval $__glxinfo_cmd
 493     eval $__glxgears_cmd
 494     eval $__es2info_cmd
 495     eval $__es2gears_cmd
 496     export LIBGL_ALWAYS_SOFTWARE=true
 497     eval $__glxinfo_cmd
 498     eval $__glxgears_cmd
 499     eval $__es2info_cmd
 500     eval $__es2gears_cmd
 501     export LIBGL_ALWAYS_SOFTWARE=true
 502     export GALLIUM_DRIVER=softpipe
 503     eval $__glxinfo_cmd
 504     eval $__glxgears_cmd
 505     eval $__es2info_cmd
 506     eval $__es2gears_cmd
 507     # Smoke test DOTA2
 508     unset LD_LIBRARY_PATH
 509     test "x$__old_ld" != 'x' &amp;&amp; export LD_LIBRARY_PATH="$__old_ld" &amp;&amp; unset __old_ld
 510     unset LIBGL_DRIVERS_PATH
 511     unset LIBGL_DEBUG
 512     unset LIBGL_ALWAYS_SOFTWARE
 513     unset GALLIUM_DRIVER
 514     export VK_ICD_FILENAMES=`pwd`/test/usr/local/share/vulkan/icd.d/intel_icd.x86_64.json
 515     steam steam://rungameid/570  -vconsole -vulkan
 516     unset VK_ICD_FILENAMES
 517 </pre>
 518
 519 <h3>Create release notes for the new release</h3>
 520
 521 <p>
 522 The release notes are completely generated by the
 523 <pre>bin/gen_release_notes.py</pre> script. Simply run this script before
 524 bumping the version
 525
 526 The only thing left to do is add the sha256 sums.
 527 </p>
 528
 529 <h3>Update version in file VERSION</h3>
 530
 531 <p>
 532 Increment the version contained in the file VERSION at Mesa's top-level, then
 533 commit this change.
 534 </p>
 535
 536 <p>
 537 Commit these changes and push the branch.
 538 </p>
 539
 540 <pre>
 541         git push origin HEAD
 542 </pre>
 543
 544
 545 <h3>Use the release.sh script from xorg <a href="https://cgit.freedesktop.org/xorg/util/modular/">util-modular</a></h3>
 546
 547 <p>
 548 Start the release process.
 549 </p>
 550
 551 <pre>
 552         # For the dist/distcheck, you may want to specify which LLVM to use:
 553         # export LLVM_CONFIG=/usr/lib/llvm-3.9/bin/llvm-config
 554         ../relative/path/to/release.sh . # append --dist if you've already done distcheck above
 555 </pre>
 556
 557 <p>
 558 Pay close attention to the prompts as you might be required to enter your GPG
 559 and SSH passphrase(s) to sign and upload the files, respectively.
 560 </p>
 561
 562 <h3>Add the sha256sums to the release notes</h3>
 563
 564 <p>
 565 Edit docs/relnotes/X.Y.Z.html to add the sha256sums as available in the mesa-X.Y.Z.announce template. Commit this change.
 566 </p>
 567
 568 <h3>Back on mesa master, add the new release notes into the tree</h3>
 569
 570 <p>
 571 Something like the following steps will do the trick:
 572 </p>
 573
 574 <pre>
 575         git cherry-pick -x X.Y~1
 576         git cherry-pick -x X.Y
 577 </pre>
 578
 579 <p>Then run the <pre>./bin/post_verison.py X.Y.Z</pre>, where X.Y.Z is the
 580 version you just made. This will updated docs/relnotes.html and
 581 docs/index.html. Remove docs/release-calendar.html. Then commit and push:
 582 </p>
 583
 584 <pre>
 585         git commit -as -m "docs: update calendar, add news item and link release notes for X.Y.Z"
 586         git push origin master X.Y
 587 </pre>
 588
 589
 590 <h2 id="announce">Announce the release</h2>
 591
 592 <p>
 593 Use the generated template during the releasing process.
 594 </p>
 595
 596 <p>
 597 Again, pay attention to add a note to warn about a final release in a
 598 series, if that is the case.
 599 </p>
 600
 601
 602 <h2 id="gitlab">Update gitlab issues</h2>
 603
 604 <p>
 605 Parse through the bugreports as listed in the docs/relnotes/X.Y.Z.html
 606 document. If there's outstanding action, close the bug referencing the commit
 607 ID which addresses the bug and mention the Mesa version that has the fix.
 608 </p>
 609
 610 <p>
 611 Note: the above is not applicable to all the reports, so use common sense.
 612 </p>
 613
 614
 615 </div>
 616 </body>
 617 </html>