docs/devinfo.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>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>Development Notes</h1>
  18
  19
  20 <ul>
  21 <li><a href="#style">Coding Style</a>
  22 <li><a href="#submitting">Submitting Patches</a>
  23 <li><a href="#release">Making a New Mesa Release</a>
  24 <li><a href="#extensions">Adding Extensions</a>
  25 </ul>
  26
  27
  28 <h2 id="style">Coding Style</h2>
  29
  30 <p>
  31 Mesa is over 20 years old and the coding style has evolved over time.
  32 Some old parts use a style that's a bit out of date.
  33
  34 Different sections of mesa can use different coding style as set in the local
  35 EditorConfig (.editorconfig) and/or Emacs (.dir-locals.el) file.
  36
  37 Alternatively the following is applicable.
  38
  39 If the guidelines below don't cover something, try following the format of
  40 existing, neighboring code.
  41 </p>
  42
  43 <p>
  44 Basic formatting guidelines
  45 </p>
  46
  47 <ul>
  48 <li>3-space indentation, no tabs.
  49 <li>Limit lines to 78 or fewer characters.  The idea is to prevent line
  50 wrapping in 80-column editors and terminals.  There are exceptions, such
  51 as if you're defining a large, static table of information.
  52 <li>Opening braces go on the same line as the if/for/while statement.
  53 For example:
  54 <pre>
  55    if (condition) {
  56       foo;
  57    } else {
  58       bar;
  59    }
  60 </pre>
  61
  62 <li>Put a space before/after operators.  For example, <tt>a = b + c;</tt>
  63 and not <tt>a=b+c;</tt>
  64
  65 <li>This GNU indent command generally does the right thing for formatting:
  66 <pre>
  67    indent -br -i3 -npcs --no-tabs infile.c -o outfile.c
  68 </pre>
  69
  70 <li>Use comments wherever you think it would be helpful for other developers.
  71 Several specific cases and style examples follow.  Note that we roughly
  72 follow <a href="http://www.stack.nl/~dimitri/doxygen/">Doxygen</a> conventions.
  73 <br>
  74 <br>
  75 Single-line comments:
  76 <pre>
  77    /* null-out pointer to prevent dangling reference below */
  78    bufferObj = NULL;
  79 </pre>
  80 Or,
  81 <pre>
  82    bufferObj = NULL;  /* prevent dangling reference below */
  83 </pre>
  84 Multi-line comment:
  85 <pre>
  86    /* If this is a new buffer object id, or one which was generated but
  87     * never used before, allocate a buffer object now.
  88     */
  89 </pre>
  90 We try to quote the OpenGL specification where prudent:
  91 <pre>
  92    /* Page 38 of the PDF of the OpenGL ES 3.0 spec says:
  93     *
  94     *     "An INVALID_OPERATION error is generated for any of the following
  95     *     conditions:
  96     *
  97     *     * <length> is zero."
  98     *
  99     * Additionally, page 94 of the PDF of the OpenGL 4.5 core spec
 100     * (30.10.2014) also says this, so it's no longer allowed for desktop GL,
 101     * either.
 102     */
 103 </pre>
 104 Function comment example:
 105 <pre>
 106    /**
 107     * Create and initialize a new buffer object.  Called via the
 108     * ctx->Driver.CreateObject() driver callback function.
 109     * \param  name  integer name of the object
 110     * \param  type  one of GL_FOO, GL_BAR, etc.
 111     * \return  pointer to new object or NULL if error
 112     */
 113    struct gl_object *
 114    _mesa_create_object(GLuint name, GLenum type)
 115    {
 116       /* function body */
 117    }
 118 </pre>
 119
 120 <li>Put the function return type and qualifiers on one line and the function
 121 name and parameters on the next, as seen above.  This makes it easy to use
 122 <code>grep ^function_name dir/*</code> to find function definitions.  Also,
 123 the opening brace goes on the next line by itself (see above.)
 124
 125 <li>Function names follow various conventions depending on the type of function:
 126 <pre>
 127    glFooBar()       - a public GL entry point (in glapi_dispatch.c)
 128    _mesa_FooBar()   - the internal immediate mode function
 129    save_FooBar()    - retained mode (display list) function in dlist.c
 130    foo_bar()        - a static (private) function
 131    _mesa_foo_bar()  - an internal non-static Mesa function
 132 </pre>
 133
 134 <li>Constants, macros and enumerant names are ALL_UPPERCASE, with _ between
 135 words.
 136 <li>Mesa usually uses camel case for local variables (Ex: "localVarname")
 137 while gallium typically uses underscores (Ex: "local_var_name").
 138 <li>Global variables are almost never used because Mesa should be thread-safe.
 139
 140 <li>Booleans.  Places that are not directly visible to the GL API
 141 should prefer the use of <tt>bool</tt>, <tt>true</tt>, and
 142 <tt>false</tt> over <tt>GLboolean</tt>, <tt>GL_TRUE</tt>, and
 143 <tt>GL_FALSE</tt>.  In C code, this may mean that
 144 <tt>#include &lt;stdbool.h&gt;</tt> needs to be added.  The
 145 <tt>try_emit_</tt>* methods in src/mesa/program/ir_to_mesa.cpp and
 146 src/mesa/state_tracker/st_glsl_to_tgsi.cpp can serve as examples.
 147
 148 </ul>
 149
 150
 151 <h2 id="submitting">Submitting patches</h2>
 152
 153 <p>
 154 The basic guidelines for submitting patches are:
 155 </p>
 156
 157 <ul>
 158 <li>Patches should be sufficiently tested before submitting.
 159 <li>Code patches should follow Mesa coding conventions.
 160 <li>Whenever possible, patches should only effect individual Mesa/Gallium
 161 components.
 162 <li>Patches should never introduce build breaks and should be bisectable (see
 163 <code>git bisect</code>.)
 164 <li>Patches should be properly formatted (see below).
 165 <li>Patches should be submitted to mesa-dev for review using
 166 <code>git send-email</code>.
 167 <li>Patches should not mix code changes with code formatting changes (except,
 168 perhaps, in very trivial cases.)
 169 </ul>
 170
 171 <h3>Patch formatting</h3>
 172
 173 <p>
 174 The basic rules for patch formatting are:
 175 </p>
 176
 177 <ul>
 178 <li>Lines should be limited to 75 characters or less so that git logs
 179 displayed in 80-column terminals avoid line wrapping.  Note that git
 180 log uses 4 spaces of indentation (4 + 75 &lt; 80).
 181 <li>The first line should be a short, concise summary of the change prefixed
 182 with a module name.  Examples:
 183 <pre>
 184     mesa: Add support for querying GL_VERTEX_ATTRIB_ARRAY_LONG
 185
 186     gallium: add PIPE_CAP_DEVICE_RESET_STATUS_QUERY
 187
 188     i965: Fix missing type in local variable declaration.
 189 </pre>
 190 <li>Subsequent patch comments should describe the change in more detail,
 191 if needed.  For example:
 192 <pre>
 193     i965: Remove end-of-thread SEND alignment code.
 194
 195     This was present in Eric's initial implementation of the compaction code
 196     for Sandybridge (commit 077d01b6). There is no documentation saying this
 197     is necessary, and removing it causes no regressions in piglit on any
 198     platform.
 199 </pre>
 200 <li>A "Signed-off-by:" line is not required, but not discouraged either.
 201 <li>If a patch address a bugzilla issue, that should be noted in the
 202 patch comment.  For example:
 203 <pre>
 204    Bugzilla: https://bugs.freedesktop.org/show_bug.cgi?id=89689
 205 </pre>
 206 <li>If there have been several revisions to a patch during the review
 207 process, they should be noted such as in this example:
 208 <pre>
 209     st/mesa: add ARB_texture_stencil8 support (v4)
 210
 211     if we support stencil texturing, enable texture_stencil8
 212     there is no requirement to support native S8 for this,
 213     the texture can be converted to x24s8 fine.
 214
 215     v2: fold fixes from Marek in:
 216        a) put S8 last in the list
 217        b) fix renderable to always test for d/s renderable
 218         fixup the texture case to use a stencil only format
 219         for picking the format for the texture view.
 220     v3: hit fallback for getteximage
 221     v4: put s8 back in front, it shouldn't get picked now (Ilia)
 222 </pre>
 223 <li>If someone tested your patch, document it with a line like this:
 224 <pre>
 225     Tested-by: Joe Hacker &lt;jhacker@foo.com&gt;
 226 </pre>
 227 <li>If the patch was reviewed (usually the case) or acked by someone,
 228 that should be documented with:
 229 <pre>
 230     Reviewed-by: Joe Hacker &lt;jhacker@foo.com&gt;
 231     Acked-by: Joe Hacker &lt;jhacker@foo.com&gt;
 232 </pre>
 233 </ul>
 234
 235
 236
 237 <h3>Testing Patches</h3>
 238
 239 <p>
 240 It should go without saying that patches must be tested.  In general,
 241 do whatever testing is prudent.
 242 </p>
 243
 244 <p>
 245 You should always run the Mesa test suite before submitting patches.
 246 The test suite can be run using the 'make check' command. All tests
 247 must pass before patches will be accepted, this may mean you have
 248 to update the tests themselves.
 249 </p>
 250
 251 <p>
 252 Whenever possible and applicable, test the patch with
 253 <a href="http://piglit.freedesktop.org">Piglit</a> and/or
 254 <a href="https://android.googlesource.com/platform/external/deqp/">dEQP</a>
 255 to check for regressions.
 256 </p>
 257
 258
 259 <h3>Mailing Patches</h3>
 260
 261 <p>
 262 Patches should be sent to the mesa-dev mailing list for review:
 263 <a href="https://lists.freedesktop.org/mailman/listinfo/mesa-dev">
 264 mesa-dev@lists.freedesktop.org<a/>.
 265 When submitting a patch make sure to use
 266 <a href="https://git-scm.com/docs/git-send-email">git send-email</a>
 267 rather than attaching patches to emails. Sending patches as
 268 attachments prevents people from being able to provide in-line review
 269 comments.
 270 </p>
 271
 272 <p>
 273 When submitting follow-up patches you can use --in-reply-to to make v2, v3,
 274 etc patches show up as replies to the originals. This usually works well
 275 when you're sending out updates to individual patches (as opposed to
 276 re-sending the whole series). Using --in-reply-to makes
 277 it harder for reviewers to accidentally review old patches.
 278 </p>
 279
 280 <p>
 281 When submitting follow-up patches you should also login to
 282 <a href="https://patchwork.freedesktop.org">patchwork</a> and change the
 283 state of your old patches to Superseded.
 284 </p>
 285
 286 <h3>Reviewing Patches</h3>
 287
 288 <p>
 289 When you've reviewed a patch on the mailing list, please be unambiguous
 290 about your review.  That is, state either
 291 <pre>
 292     Reviewed-by: Joe Hacker &lt;jhacker@foo.com&gt;
 293 </pre>
 294 or
 295 <pre>
 296     Acked-by: Joe Hacker &lt;jhacker@foo.com&gt;
 297 </pre>
 298 Rather than saying just "LGTM" or "Seems OK".
 299 </p>
 300
 301 <p>
 302 If small changes are suggested, it's OK to say something like:
 303 <pre>
 304    With the above fixes, Reviewed-by: Joe Hacker &lt;jhacker@foo.com&gt;
 305 </pre>
 306 which tells the patch author that the patch can be committed, as long
 307 as the issues are resolved first.
 308 </p>
 309
 310
 311 <h3>Marking a commit as a candidate for a stable branch</h3>
 312
 313 <p>
 314 If you want a commit to be applied to a stable branch,
 315 you should add an appropriate note to the commit message.
 316 </p>
 317
 318 <p>
 319 Here are some examples of such a note:
 320 </p>
 321 <ul>
 322   <li>CC: &lt;mesa-stable@lists.freedesktop.org&gt;</li>
 323   <li>CC: "9.2 10.0" &lt;mesa-stable@lists.freedesktop.org&gt;</li>
 324   <li>CC: "10.0" &lt;mesa-stable@lists.freedesktop.org&gt;</li>
 325 </ul>
 326
 327 Simply adding the CC to the mesa-stable list address is adequate to nominate
 328 the commit for the most-recently-created stable branch. It is only necessary
 329 to specify a specific branch name, (such as "9.2 10.0" or "10.0" in the
 330 examples above), if you want to nominate the commit for an older stable
 331 branch. And, as in these examples, you can nominate the commit for the older
 332 branch in addition to the more recent branch, or nominate the commit
 333 exclusively for the older branch.
 334
 335 This "CC" syntax for patch nomination will cause patches to automatically be
 336 copied to the mesa-stable@ mailing list when you use "git send-email" to send
 337 patches to the mesa-dev@ mailing list. Also, if you realize that a commit
 338 should be nominated for the stable branch after it has already been committed,
 339 you can send a note directly to the mesa-stable@lists.freedesktop.org where
 340 the Mesa stable-branch maintainers will receive it. Be sure to mention the
 341 commit ID of the commit of interest (as it appears in the mesa master branch).
 342
 343 The latest set of patches that have been nominated, accepted, or rejected for
 344 the upcoming stable release can always be seen on the
 345 <a href="http://cworth.org/~cworth/mesa-stable-queue/">Mesa Stable Queue</a>
 346 page.
 347
 348 <h3>Criteria for accepting patches to the stable branch</h3>
 349
 350 Mesa has a designated release manager for each stable branch, and the release
 351 manager is the only developer that should be pushing changes to these
 352 branches. Everyone else should simply nominate patches using the mechanism
 353 described above.
 354
 355 The stable-release manager will work with the list of nominated patches, and
 356 for each patch that meets the crtieria below will cherry-pick the patch with:
 357 <code>git cherry-pick -x &lt;commit&gt;</code>. The <code>-x</code> option is
 358 important so that the picked patch references the comit ID of the original
 359 patch.
 360
 361 The stable-release manager may at times need to force-push changes to the
 362 stable branches, for example, to drop a previously-picked patch that was later
 363 identified as causing a regression). These force-pushes may cause changes to
 364 be lost from the stable branch if developers push things directly. Consider
 365 yourself warned.
 366
 367 The stable-release manager is also given broad discretion in rejecting patches
 368 that have been nominated for the stable branch. The most basic rule is that
 369 the stable branch is for bug fixes only, (no new features, no
 370 regressions). Here is a non-exhaustive list of some reasons that a patch may
 371 be rejected:
 372
 373 <ul>
 374   <li>Patch introduces a regression. Any reported build breakage or other
 375   regression caused by a particular patch, (game no longer work, piglit test
 376   changes from PASS to FAIL), is justification for rejecting a patch.</li>
 377
 378   <li>Patch is too large, (say, larger than 100 lines)</li>
 379
 380   <li>Patch is not a fix. For example, a commit that moves code around with no
 381   functional change should be rejected.</li>
 382
 383   <li>Patch fix is not clearly described. For example, a commit message
 384   of only a single line, no description of the bug, no mention of bugzilla,
 385   etc.</li>
 386
 387   <li>Patch has not obviously been reviewed, For example, the commit message
 388   has no Reviewed-by, Signed-off-by, nor Tested-by tags from anyone but the
 389   author.</li>
 390
 391   <li>Patch has not already been merged to the master branch. As a rule, bug
 392   fixes should never be applied first to a stable branch. Patches should land
 393   first on the master branch and then be cherry-picked to a stable
 394   branch. (This is to avoid future releases causing regressions if the patch
 395   is not also applied to master.) The only things that might look like
 396   exceptions would be backports of patches from master that happen to look
 397   significantly different.</li>
 398
 399   <li>Patch depends on too many other patches. Ideally, all stable-branch
 400   patches should be self-contained. It sometimes occurs that a single, logical
 401   bug-fix occurs as two separate patches on master, (such as an original
 402   patch, then a subsequent fix-up to that patch). In such a case, these two
 403   patches should be squashed into a single, self-contained patch for the
 404   stable branch. (Of course, if the squashing makes the patch too large, then
 405   that could be a reason to reject the patch.)</li>
 406
 407   <li>Patch includes new feature development, not bug fixes. New OpenGL
 408   features, extensions, etc. should be applied to Mesa master and included in
 409   the next major release. Stable releases are intended only for bug fixes.
 410
 411   Note: As an exception to this rule, the stable-release manager may accept
 412   hardware-enabling "features". For example, backports of new code to support
 413   a newly-developed hardware product can be accepted if they can be reasonably
 414   determined to not have effects on other hardware.</li>
 415
 416   <li>Patch is a performance optimization. As a rule, performance patches are
 417   not candidates for the stable branch. The only exception might be a case
 418   where an application's performance was recently severely impacted so as to
 419   become unusable. The fix for this performance regression could then be
 420   considered for a stable branch. The optimization must also be
 421   non-controversial and the patches still need to meet the other criteria of
 422   being simple and self-contained</li>
 423
 424   <li>Patch introduces a new failure mode (such as an assert). While the new
 425   assert might technically be correct, for example to make Mesa more
 426   conformant, this is not the kind of "bug fix" we want in a stable
 427   release. The potential problem here is that an OpenGL program that was
 428   previously working, (even if technically non-compliant with the
 429   specification), could stop working after this patch. So that would be a
 430   regression that is unaacceptable for the stable branch.</li>
 431 </ul>
 432
 433
 434 <h2 id="release">Making a New Mesa Release</h2>
 435
 436 <p>
 437 These are the instructions for making a new Mesa release.
 438 </p>
 439
 440 <h3>Get latest source files</h3>
 441 <p>
 442 Use git to get the latest Mesa files from the git repository, from whatever
 443 branch is relevant. This document uses the convention X.Y.Z for the release
 444 being created, which should be created from a branch named X.Y.
 445 </p>
 446
 447 <h3>Perform basic testing</h3>
 448 <p>
 449 The release manager should, at the very least, test the code by compiling it,
 450 installing it, and running the latest piglit to ensure that no piglit tests
 451 have regressed since the previous release.
 452 </p>
 453
 454 <p>
 455 The release manager should do this testing with at least one hardware driver,
 456 (say, whatever is contained in the local development machine), as well as on
 457 both Gallium and non-Gallium software drivers. The software testing can be
 458 performed by running piglit with the following environment-variable set:
 459 </p>
 460
 461 <pre>
 462 LIBGL_ALWAYS_SOFTWARE=1
 463 </pre>
 464
 465 And Gallium vs. non-Gallium software drivers can be obtained by using the
 466 following configure flags on separate builds:
 467
 468 <pre>
 469 --with-dri-drivers=swrast
 470 --with-gallium-drivers=swrast
 471 </pre>
 472
 473 <p>
 474 Note: If both options are given in one build, both swrast_dri.so drivers will
 475 be compiled, but only one will be installed. The following command can be used
 476 to ensure the correct driver is being tested:
 477 </p>
 478
 479 <pre>
 480 LIBGL_ALWAYS_SOFTWARE=1 glxinfo | grep "renderer string"
 481 </pre>
 482
 483 If any regressions are found in this testing with piglit, stop here, and do
 484 not perform a release until regressions are fixed.
 485
 486 <h3>Update version in file VERSION</h3>
 487
 488 <p>
 489 Increment the version contained in the file VERSION at Mesa's top-level, then
 490 commit this change.
 491 </p>
 492
 493 <h3>Create release notes for the new release</h3>
 494
 495 <p>
 496 Create a new file docs/relnotes/X.Y.Z.html, (follow the style of the previous
 497 release notes). Note that the sha256sums section of the release notes should
 498 be empty at this point.
 499 </p>
 500
 501 <p>
 502 Two scripts are available to help generate portions of the release notes:
 503
 504 <pre>
 505         ./bin/bugzilla_mesa.sh
 506         ./bin/shortlog_mesa.sh
 507 </pre>
 508
 509 <p>
 510 The first script identifies commits that reference bugzilla bugs and obtains
 511 the descriptions of those bugs from bugzilla. The second script generates a
 512 log of all commits. In both cases, HTML-formatted lists are printed to stdout
 513 to be included in the release notes.
 514 </p>
 515
 516 <p>
 517 Commit these changes
 518 </p>
 519
 520 <h3>Make the release archives, signatures, and the release tag</h3>
 521 <p>
 522 From inside the Mesa directory:
 523 <pre>
 524         ./autogen.sh
 525         make -j1 tarballs
 526 </pre>
 527
 528 <p>
 529 After the tarballs are created, the sha256 checksums for the files will
 530 be computed and printed. These will be used in a step below.
 531 </p>
 532
 533 <p>
 534 It's important at this point to also verify that the constructed tar file
 535 actually builds:
 536 </p>
 537
 538 <pre>
 539         tar xjf MesaLib-X.Y.Z.tar.bz2
 540         cd Mesa-X.Y.Z
 541         ./configure --enable-gallium-llvm
 542         make -j6
 543         make install
 544 </pre>
 545
 546 <p>
 547 Some touch testing should also be performed at this point, (run glxgears or
 548 more involved OpenGL programs against the installed Mesa).
 549 </p>
 550
 551 <p>
 552 Create detached GPG signatures for each of the archive files created above:
 553 </p>
 554
 555 <pre>
 556         gpg --sign --detach MesaLib-X.Y.Z.tar.gz
 557         gpg --sign --detach MesaLib-X.Y.Z.tar.bz2
 558         gpg --sign --detach MesaLib-X.Y.Z.zip
 559 </pre>
 560
 561 <p>
 562 Tag the commit used for the build:
 563 </p>
 564
 565 <pre>
 566         git tag -s mesa-X.Y.X -m "Mesa X.Y.Z release"
 567 </pre>
 568
 569 <p>
 570 Note: It would be nice to investigate and fix the issue that causes the
 571 tarballs target to fail with multiple build process, such as with "-j4". It
 572 would also be nice to incorporate all of the above commands into a single
 573 makefile target. And instead of a custom "tarballs" target, we should
 574 incorporate things into the standard "make dist" and "make distcheck" targets.
 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 printed as part of "make
 581 tarballs" in the previous step. Commit this change.
 582 </p>
 583
 584 <h3>Push all commits and the tag created above</h3>
 585
 586 <p>
 587 This is the first step that cannot easily be undone. The release is going
 588 forward from this point:
 589 </p>
 590
 591 <pre>
 592         git push origin X.Y --tags
 593 </pre>
 594
 595 <h3>Install the release files and signatures on the distribution server</h3>
 596
 597 <p>
 598 The following commands can be used to copy the release archive files and
 599 signatures to the freedesktop.org server:
 600 </p>
 601
 602 <pre>
 603         scp MesaLib-X.Y.Z* people.freedesktop.org:
 604         ssh people.freedesktop.org
 605         cd /srv/ftp.freedesktop.org/pub/mesa
 606         mkdir X.Y.Z
 607         cd X.Y.Z
 608         mv ~/MesaLib-X.Y.Z* .
 609 </pre>
 610
 611 <h3>Back on mesa master, add the new release notes into the tree</h3>
 612
 613 <p>
 614 Something like the following steps will do the trick:
 615 </p>
 616
 617 <pre>
 618         cp docs/relnotes/X.Y.Z.html /tmp
 619         git checkout master
 620         cp /tmp/X.Y.Z.html docs/relnotes
 621         git add docs/relnotes/X.Y.Z.html
 622 </pre>
 623
 624 <p>
 625 Also, edit docs/relnotes.html to add a link to the new release notes, and edit
 626 docs/index.html to add a news entry. Then commit and push:
 627 </p>
 628
 629 <pre>
 630         git commit -a -m "docs: Import X.Y.Z release notes, add news item."
 631         git push origin
 632 </pre>
 633
 634 <h3>Update the mesa3d.org website</h3>
 635
 636 <p>
 637 NOTE: The recent release managers have not been performing this step
 638 themselves, but leaving this to Brian Paul, (who has access to the
 639 sourceforge.net hosting for mesa3d.org). Brian is more than willing to grant
 640 the permission necessary to future release managers to do this step on their
 641 own.
 642 </p>
 643
 644 <p>
 645 Update the web site by copying the docs/ directory's files to
 646 /home/users/b/br/brianp/mesa-www/htdocs/ with:
 647 <br>
 648 <code>
 649 sftp USERNAME,mesa3d@web.sourceforge.net
 650 </code>
 651 </p>
 652
 653
 654 <h3>Announce the release</h3>
 655 <p>
 656 Make an announcement on the mailing lists:
 657
 658 <em>mesa-dev@lists.freedesktop.org</em>,
 659 and
 660 <em>mesa-announce@lists.freedesktop.org</em>
 661
 662 Follow the template of previously-sent release announcements. The following
 663 command can be used to generate the log of changes to be included in the
 664 release announcement:
 665
 666 <pre>
 667         git shortlog mesa-X.Y.Z-1..mesa-X.Y.Z
 668 </pre>
 669 </p>
 670
 671
 672 <h2 id="extensions">Adding Extensions</h2>
 673
 674 <p>
 675 To add a new GL extension to Mesa you have to do at least the following.
 676
 677 <ul>
 678 <li>
 679    If glext.h doesn't define the extension, edit include/GL/gl.h and add
 680    code like this:
 681    <pre>
 682      #ifndef GL_EXT_the_extension_name
 683      #define GL_EXT_the_extension_name 1
 684      /* declare the new enum tokens */
 685      /* prototype the new functions */
 686      /* TYPEDEFS for the new functions */
 687      #endif
 688    </pre>
 689 </li>
 690 <li>
 691    In the src/mapi/glapi/gen/ directory, add the new extension functions and
 692    enums to the gl_API.xml file.
 693    Then, a bunch of source files must be regenerated by executing the
 694    corresponding Python scripts.
 695 </li>
 696 <li>
 697    Add a new entry to the <code>gl_extensions</code> struct in mtypes.h
 698    if the extension requires driver capabilities not already exposed by
 699    another extension.
 700 </li>
 701 <li>
 702    Add a new entry to the src/mesa/main/extensions_table.h file.
 703 </li>
 704 <li>
 705    From this point, the best way to proceed is to find another extension,
 706    similar to the new one, that's already implemented in Mesa and use it
 707    as an example.
 708 </li>
 709 <li>
 710    If the new extension adds new GL state, the functions in get.c, enable.c
 711    and attrib.c will most likely require new code.
 712 </li>
 713 <li>
 714    To determine if the new extension is active in the current context,
 715    use the auto-generated _mesa_has_##name_str() function defined in
 716    src/mesa/main/extensions.h.
 717 </li>
 718 <li>
 719    The dispatch tests check_table.cpp and dispatch_sanity.cpp
 720    should be updated with details about the new extensions functions. These
 721    tests are run using 'make check'
 722 </li>
 723 </ul>
 724 </p>
 725
 726
 727
 728
 729 </div>
 730 </body>
 731 </html>