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