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