| Emil Velikov | 2edc29a | 2016-11-16 18:25:41 +0000 | [diff] [blame] | 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>Development Notes</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@... |
| 215 | Cc: mesa-dev@... |
| 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@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 | * process - manual + xorg tool |
| 304 | + ^^ verify |
| 305 | + touch test -> glxgears/info dota2vk |
| 306 | |
| 307 | |
| 308 | <p> |
| 309 | These are the instructions for making a new Mesa release. |
| 310 | </p> |
| 311 | |
| 312 | <h3>Get latest source files</h3> |
| 313 | <p> |
| 314 | Ensure the latest code is available - both in your local master and the |
| 315 | relevant branch. |
| 316 | </p> |
| 317 | |
| 318 | <h3>Perform basic testing</h3> |
| 319 | <p> |
| 320 | Most of the testing should already be done during the |
| 321 | <a href="#pickntest">cherry-pick</a> and |
| 322 | <a href="#prerelease">pre-announce</a> stages. |
| 323 | |
| 324 | So we do a quick 'touch test' |
| 325 | <ul> |
| 326 | <li>make distcheck (you can omit this if you're not using --dist below) |
| 327 | <li>scons (from release tarball) |
| 328 | <li>the produced binaries work |
| 329 | </ul> |
| 330 | |
| 331 | <p> |
| 332 | Here is one solution that I've been using. |
| 333 | </p> |
| 334 | |
| 335 | <pre> |
| 336 | git clean -fXd; git clean -nxd |
| 337 | read # quick cross check any outstanding files |
| 338 | export __mesa_root=../ |
| 339 | export __build_root=./foo |
| 340 | chmod 755 -fR $__build_root; rm -rf $__build_root |
| 341 | mkdir -p $__build_root && cd $__build_root |
| 342 | |
| 343 | $__mesa_root/autogen.sh --enable-llvm-shared-libs && make -j2 distcheck |
| 344 | |
| 345 | # Build check the tarballs (scons) |
| 346 | tar -xaf mesa-*.tar.xz && cd mesa-* && scons && cd .. |
| 347 | |
| 348 | # Test the automake binaries |
| 349 | tar -xaf mesa-*.tar.xz && cd mesa-* |
| 350 | ./configure \ |
| 351 | --with-dri-drivers=i965,swrast \ |
| 352 | --with-gallium-drivers=swrast \ |
| 353 | --enable-llvm-shared-libs \ |
| 354 | --enable-gallium-llvm |
| 355 | make -j2 && DESTDIR=`pwd`/test make -j6 install |
| 356 | export LD_LIBRARY_PATH=`pwd`/test/usr/local/lib/ |
| 357 | export LIBGL_DRIVERS_PATH=`pwd`/test/usr/local/lib/dri/ |
| 358 | xport LIBGL_DEBUG=verbose |
| 359 | glxinfo | egrep -o "Mesa.*" |
| 360 | glxgears |
| 361 | export LIBGL_ALWAYS_SOFTWARE=1 |
| 362 | glxinfo | egrep -o "Mesa.*|Gallium.*" |
| 363 | glxgears |
| 364 | export LIBGL_ALWAYS_SOFTWARE=1 |
| 365 | export GALLIUM_DRIVER=softpipe |
| 366 | glxinfo | egrep -o "Mesa.*|Gallium.*" |
| 367 | glxgears |
| 368 | </pre> |
| 369 | |
| 370 | <h3>Update version in file VERSION</h3> |
| 371 | |
| 372 | <p> |
| 373 | Increment the version contained in the file VERSION at Mesa's top-level, then |
| 374 | commit this change. |
| 375 | </p> |
| 376 | |
| 377 | <h3>Create release notes for the new release</h3> |
| 378 | |
| 379 | <p> |
| 380 | Create a new file docs/relnotes/X.Y.Z.html, (follow the style of the previous |
| 381 | release notes). Note that the sha256sums section of the release notes should |
| 382 | be empty (TBD) at this point. |
| 383 | </p> |
| 384 | |
| 385 | <p> |
| 386 | Two scripts are available to help generate portions of the release notes: |
| 387 | |
| 388 | <pre> |
| 389 | ./bin/bugzilla_mesa.sh |
| 390 | ./bin/shortlog_mesa.sh |
| 391 | </pre> |
| 392 | |
| 393 | <p> |
| 394 | The first script identifies commits that reference bugzilla bugs and obtains |
| 395 | the descriptions of those bugs from bugzilla. The second script generates a |
| 396 | log of all commits. In both cases, HTML-formatted lists are printed to stdout |
| 397 | to be included in the release notes. |
| 398 | </p> |
| 399 | |
| 400 | <p> |
| 401 | Commit these changes and push the branch. |
| 402 | </p> |
| 403 | <pre> |
| 404 | git push origin HEAD |
| 405 | </pre> |
| 406 | |
| 407 | |
| 408 | <h3>Use the release.sh script from xorg util-macros</h3> |
| 409 | |
| 410 | <p> |
| Emil Velikov | 2edc29a | 2016-11-16 18:25:41 +0000 | [diff] [blame] | 411 | Ensure that the mesa git tree is clean via <code>git clean -fXd</code> and |
| 412 | start the release process. |
| 413 | </p> |
| 414 | <pre> |
| 415 | ../relative/path/to/release.sh . # append --dist if you've already done distcheck above |
| 416 | </pre> |
| 417 | |
| 418 | <p> |
| 419 | Pay close attention to the prompts as you might be required to enter your GPG |
| 420 | and SSH passphrase(s) to sign and upload the files, respectively. |
| 421 | </p> |
| 422 | |
| 423 | <h3>Add the sha256sums to the release notes</h3> |
| 424 | |
| 425 | <p> |
| 426 | Edit docs/relnotes/X.Y.Z.html to add the sha256sums as availabe in the mesa-X.Y.Z.announce template. Commit this change. |
| 427 | </p> |
| 428 | |
| 429 | <h3>Back on mesa master, add the new release notes into the tree</h3> |
| 430 | |
| 431 | <p> |
| 432 | Something like the following steps will do the trick: |
| 433 | </p> |
| 434 | |
| 435 | <pre> |
| 436 | git cherry-pick -x X.Y~1 |
| 437 | git cherry-pick -x X.Y |
| 438 | </pre> |
| 439 | |
| 440 | <p> |
| 441 | Also, edit docs/relnotes.html to add a link to the new release notes, and edit |
| 442 | docs/index.html to add a news entry. Then commit and push: |
| 443 | </p> |
| 444 | |
| 445 | <pre> |
| 446 | git commit -as -m "docs: add news item and link release notes for X.Y.Z" |
| 447 | git push origin master X.Y |
| 448 | </pre> |
| 449 | |
| 450 | |
| 451 | <h1 id="announce">Announce the release</h1> |
| 452 | <p> |
| 453 | Use the generated template during the releasing process. |
| 454 | </p> |
| 455 | |
| 456 | |
| 457 | <h1 id="website">Update the mesa3d.org website</h1> |
| 458 | |
| 459 | <p> |
| 460 | NOTE: The recent release managers have not been performing this step |
| 461 | themselves, but leaving this to Brian Paul, (who has access to the |
| 462 | sourceforge.net hosting for mesa3d.org). Brian is more than willing to grant |
| 463 | the permission necessary to future release managers to do this step on their |
| 464 | own. |
| 465 | </p> |
| 466 | |
| 467 | <p> |
| 468 | Update the web site by copying the docs/ directory's files to |
| 469 | /home/users/b/br/brianp/mesa-www/htdocs/ with: |
| 470 | <br> |
| 471 | <code> |
| 472 | sftp USERNAME,mesa3d@web.sourceforge.net |
| 473 | </code> |
| 474 | </p> |
| 475 | |
| 476 | |
| 477 | <h1 id="bugzilla">Update Bugzilla</h1> |
| 478 | |
| 479 | <p> |
| 480 | Parse through the bugreports as listed in the docs/relnotes/X.Y.Z.html |
| 481 | document. |
| 482 | <br> |
| 483 | If there's outstanding action, close the bug referencing the commit ID which |
| 484 | addresses the bug and mention the Mesa version that has the fix. |
| 485 | </p> |
| 486 | |
| 487 | <p> |
| 488 | Note: the above is not applicable to all the reports, so use common sense. |
| 489 | </p> |
| 490 | |
| 491 | |
| 492 | </div> |
| 493 | </body> |
| 494 | </html> |