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