Andreas Boll | ecd5c7c | 2012-06-12 09:05:03 +0200 | [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> |
Brian Paul | 0b27ace | 2003-03-08 17:38:57 +0000 | [diff] [blame] | 9 | |
Andreas Boll | b5da52a | 2012-09-18 18:57:02 +0200 | [diff] [blame] | 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 | |
Andreas Boll | ecd5c7c | 2012-06-12 09:05:03 +0200 | [diff] [blame] | 17 | <h1>Development Notes</h1> |
Brian Paul | 0b27ace | 2003-03-08 17:38:57 +0000 | [diff] [blame] | 18 | |
| 19 | |
Brian Paul | 5183061 | 2004-08-17 14:08:59 +0000 | [diff] [blame] | 20 | <ul> |
Brian Paul | 98f2f47 | 2015-05-25 09:13:09 -0600 | [diff] [blame^] | 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> |
Brian Paul | 5183061 | 2004-08-17 14:08:59 +0000 | [diff] [blame] | 25 | </ul> |
Brian Paul | 0b27ace | 2003-03-08 17:38:57 +0000 | [diff] [blame] | 26 | |
| 27 | |
Brian Paul | 98f2f47 | 2015-05-25 09:13:09 -0600 | [diff] [blame^] | 28 | <h2 id="style">Coding Style</h2> |
Brian Paul | 0b27ace | 2003-03-08 17:38:57 +0000 | [diff] [blame] | 29 | |
| 30 | <p> |
| 31 | Mesa's code style has changed over the years. Here's the latest. |
| 32 | </p> |
| 33 | |
| 34 | <p> |
| 35 | Comment your code! It's extremely important that open-source code be |
| 36 | well documented. Also, strive to write clean, easily understandable code. |
| 37 | </p> |
| 38 | |
| 39 | <p> |
| 40 | 3-space indentation |
| 41 | </p> |
| 42 | |
| 43 | <p> |
| 44 | If you use tabs, set them to 8 columns |
| 45 | </p> |
| 46 | |
| 47 | <p> |
Paul Berry | 4396826 | 2011-08-16 14:09:32 -0700 | [diff] [blame] | 48 | Line width: the preferred width to fill comments and code in Mesa is 78 |
| 49 | columns. Exceptions are sometimes made for clarity (e.g. tabular data is |
| 50 | sometimes filled to a much larger width so that extraneous carriage returns |
| 51 | don't obscure the table). |
| 52 | </p> |
| 53 | |
| 54 | <p> |
Brian Paul | 0b27ace | 2003-03-08 17:38:57 +0000 | [diff] [blame] | 55 | Brace example: |
| 56 | </p> |
| 57 | <pre> |
| 58 | if (condition) { |
| 59 | foo; |
| 60 | } |
| 61 | else { |
| 62 | bar; |
| 63 | } |
Paul Berry | 4396826 | 2011-08-16 14:09:32 -0700 | [diff] [blame] | 64 | |
| 65 | switch (condition) { |
| 66 | case 0: |
| 67 | foo(); |
| 68 | break; |
| 69 | |
| 70 | case 1: { |
| 71 | ... |
| 72 | break; |
| 73 | } |
| 74 | |
| 75 | default: |
| 76 | ... |
| 77 | break; |
| 78 | } |
Brian Paul | 0b27ace | 2003-03-08 17:38:57 +0000 | [diff] [blame] | 79 | </pre> |
| 80 | |
| 81 | <p> |
| 82 | Here's the GNU indent command which will best approximate my preferred style: |
Paul Berry | 4396826 | 2011-08-16 14:09:32 -0700 | [diff] [blame] | 83 | (Note that it won't format switch statements in the preferred way) |
Brian Paul | 0b27ace | 2003-03-08 17:38:57 +0000 | [diff] [blame] | 84 | </p> |
| 85 | <pre> |
Brian Paul | e3f41ce | 2006-03-31 23:10:21 +0000 | [diff] [blame] | 86 | indent -br -i3 -npcs --no-tabs infile.c -o outfile.c |
Brian Paul | 0b27ace | 2003-03-08 17:38:57 +0000 | [diff] [blame] | 87 | </pre> |
| 88 | |
| 89 | |
| 90 | <p> |
| 91 | Local variable name example: localVarName (no underscores) |
| 92 | </p> |
| 93 | |
| 94 | <p> |
| 95 | Constants and macros are ALL_UPPERCASE, with _ between words |
| 96 | </p> |
| 97 | |
| 98 | <p> |
Brian Paul | 65b7905 | 2004-11-22 17:49:15 +0000 | [diff] [blame] | 99 | Global variables are not allowed. |
Brian Paul | 0b27ace | 2003-03-08 17:38:57 +0000 | [diff] [blame] | 100 | </p> |
| 101 | |
| 102 | <p> |
| 103 | Function name examples: |
| 104 | </p> |
| 105 | <pre> |
Chia-I Wu | 27d260b4 | 2010-02-24 11:20:14 +0800 | [diff] [blame] | 106 | glFooBar() - a public GL entry point (in glapi_dispatch.c) |
Brian Paul | 0b27ace | 2003-03-08 17:38:57 +0000 | [diff] [blame] | 107 | _mesa_FooBar() - the internal immediate mode function |
| 108 | save_FooBar() - retained mode (display list) function in dlist.c |
| 109 | foo_bar() - a static (private) function |
| 110 | _mesa_foo_bar() - an internal non-static Mesa function |
| 111 | </pre> |
| 112 | |
Kai Wasserbäch | dbec3a5 | 2011-08-23 10:48:58 +0200 | [diff] [blame] | 113 | <p> |
| 114 | Places that are not directly visible to the GL API should prefer the use |
| 115 | of <tt>bool</tt>, <tt>true</tt>, and |
| 116 | <tt>false</tt> over <tt>GLboolean</tt>, <tt>GL_TRUE</tt>, and |
| 117 | <tt>GL_FALSE</tt>. In C code, this may mean that |
Kai Wasserbäch | e106d4c | 2011-08-27 17:51:47 +0200 | [diff] [blame] | 118 | <tt>#include <stdbool.h></tt> needs to be added. The |
Kai Wasserbäch | dbec3a5 | 2011-08-23 10:48:58 +0200 | [diff] [blame] | 119 | <tt>try_emit_</tt>* methods in src/mesa/program/ir_to_mesa.cpp and |
Kai Wasserbäch | e106d4c | 2011-08-27 17:51:47 +0200 | [diff] [blame] | 120 | src/mesa/state_tracker/st_glsl_to_tgsi.cpp can serve as examples. |
Kai Wasserbäch | dbec3a5 | 2011-08-23 10:48:58 +0200 | [diff] [blame] | 121 | </p> |
| 122 | |
Brian Paul | 98f2f47 | 2015-05-25 09:13:09 -0600 | [diff] [blame^] | 123 | |
| 124 | <h2 id="submitting">Submitting patches</h2> |
Timothy Arceri | 2382011 | 2013-09-05 02:54:00 -0600 | [diff] [blame] | 125 | |
| 126 | <p> |
| 127 | You should always run the Mesa Testsuite before submitting patches. |
| 128 | The Testsuite can be run using the 'make check' command. All tests |
| 129 | must pass before patches will be accepted, this may mean you have |
| 130 | to update the tests themselves. |
| 131 | </p> |
| 132 | |
| 133 | <p> |
| 134 | Patches should be sent to the Mesa mailing list for review. |
| 135 | When submitting a patch make sure to use git send-email rather than attaching |
| 136 | patches to emails. Sending patches as attachments prevents people from being |
| 137 | able to provide in-line review comments. |
| 138 | </p> |
| 139 | |
| 140 | <p> |
| 141 | When submitting follow-up patches you can use --in-reply-to to make v2, v3, |
| 142 | etc patches show up as replies to the originals. This usually works well |
| 143 | when you're sending out updates to individual patches (as opposed to |
| 144 | re-sending the whole series). Using --in-reply-to makes |
| 145 | it harder for reviewers to accidentally review old patches. |
| 146 | </p> |
Brian Paul | 0b27ace | 2003-03-08 17:38:57 +0000 | [diff] [blame] | 147 | |
Brian Paul | 98f2f47 | 2015-05-25 09:13:09 -0600 | [diff] [blame^] | 148 | <h3>Marking a commit as a candidate for a stable branch</h3> |
Andreas Boll | f07784d | 2012-10-02 13:37:34 +0200 | [diff] [blame] | 149 | |
| 150 | <p> |
| 151 | If you want a commit to be applied to a stable branch, |
| 152 | you should add an appropriate note to the commit message. |
| 153 | </p> |
| 154 | |
| 155 | <p> |
| 156 | Here are some examples of such a note: |
| 157 | </p> |
| 158 | <ul> |
Carl Worth | d6c8365 | 2013-12-12 23:07:26 -0800 | [diff] [blame] | 159 | <li>CC: <mesa-stable@lists.freedesktop.org></li> |
| 160 | <li>CC: "9.2 10.0" <mesa-stable@lists.freedesktop.org></li> |
| 161 | <li>CC: "10.0" <mesa-stable@lists.freedesktop.org></li> |
Andreas Boll | f07784d | 2012-10-02 13:37:34 +0200 | [diff] [blame] | 162 | </ul> |
| 163 | |
Carl Worth | d6c8365 | 2013-12-12 23:07:26 -0800 | [diff] [blame] | 164 | Simply adding the CC to the mesa-stable list address is adequate to nominate |
| 165 | the commit for the most-recently-created stable branch. It is only necessary |
| 166 | to specify a specific branch name, (such as "9.2 10.0" or "10.0" in the |
| 167 | examples above), if you want to nominate the commit for an older stable |
| 168 | branch. And, as in these examples, you can nominate the commit for the older |
| 169 | branch in addition to the more recent branch, or nominate the commit |
| 170 | exclusively for the older branch. |
| 171 | |
| 172 | This "CC" syntax for patch nomination will cause patches to automatically be |
| 173 | copied to the mesa-stable@ mailing list when you use "git send-email" to send |
| 174 | patches to the mesa-dev@ mailing list. Also, if you realize that a commit |
Nathan Kidd | 0691b37 | 2014-01-03 16:44:00 -0700 | [diff] [blame] | 175 | should be nominated for the stable branch after it has already been committed, |
Carl Worth | d6c8365 | 2013-12-12 23:07:26 -0800 | [diff] [blame] | 176 | you can send a note directly to the mesa-stable@lists.freedesktop.org where |
| 177 | the Mesa stable-branch maintainers will receive it. Be sure to mention the |
| 178 | commit ID of the commit of interest (as it appears in the mesa master branch). |
Andreas Boll | 1f38fb2 | 2012-10-02 13:55:53 +0200 | [diff] [blame] | 179 | |
Carl Worth | 4546b70 | 2014-04-30 16:27:03 -0700 | [diff] [blame] | 180 | The latest set of patches that have been nominated, accepted, or rejected for |
| 181 | the upcoming stable release can always be seen on the |
Carl Worth | 399b4e2 | 2014-08-21 09:46:57 -0700 | [diff] [blame] | 182 | <a href="http://cworth.org/~cworth/mesa-stable-queue/">Mesa Stable Queue</a> |
Carl Worth | 4546b70 | 2014-04-30 16:27:03 -0700 | [diff] [blame] | 183 | page. |
| 184 | |
Brian Paul | 98f2f47 | 2015-05-25 09:13:09 -0600 | [diff] [blame^] | 185 | <h3>Criteria for accepting patches to the stable branch</h3> |
Andreas Boll | 1f38fb2 | 2012-10-02 13:55:53 +0200 | [diff] [blame] | 186 | |
Carl Worth | 399b4e2 | 2014-08-21 09:46:57 -0700 | [diff] [blame] | 187 | Mesa has a designated release manager for each stable branch, and the release |
| 188 | manager is the only developer that should be pushing changes to these |
| 189 | branches. Everyone else should simply nominate patches using the mechanism |
| 190 | described above. |
| 191 | |
| 192 | The stable-release manager will work with the list of nominated patches, and |
| 193 | for each patch that meets the crtieria below will cherry-pick the patch with: |
| 194 | <code>git cherry-pick -x <commit></code>. The <code>-x</code> option is |
| 195 | important so that the picked patch references the comit ID of the original |
| 196 | patch. |
| 197 | |
| 198 | The stable-release manager may at times need to force-push changes to the |
| 199 | stable branches, for example, to drop a previously-picked patch that was later |
| 200 | identified as causing a regression). These force-pushes may cause changes to |
| 201 | be lost from the stable branch if developers push things directly. Consider |
| 202 | yourself warned. |
| 203 | |
| 204 | The stable-release manager is also given broad discretion in rejecting patches |
| 205 | that have been nominated for the stable branch. The most basic rule is that |
| 206 | the stable branch is for bug fixes only, (no new features, no |
| 207 | regressions). Here is a non-exhaustive list of some reasons that a patch may |
| 208 | be rejected: |
| 209 | |
| 210 | <ul> |
| 211 | <li>Patch introduces a regression. Any reported build breakage or other |
| 212 | regression caused by a particular patch, (game no longer work, piglit test |
| 213 | changes from PASS to FAIL), is justification for rejecting a patch.</li> |
| 214 | |
| 215 | <li>Patch is too large, (say, larger than 100 lines)</li> |
| 216 | |
| 217 | <li>Patch is not a fix. For example, a commit that moves code around with no |
| 218 | functional change should be rejected.</li> |
| 219 | |
| 220 | <li>Patch fix is not clearly described. For example, a commit message |
| 221 | of only a single line, no description of the bug, no mention of bugzilla, |
| 222 | etc.</li> |
| 223 | |
| 224 | <li>Patch has not obviously been reviewed, For example, the commit message |
| 225 | has no Reviewed-by, Signed-off-by, nor Tested-by tags from anyone but the |
| 226 | author.</li> |
| 227 | |
| 228 | <li>Patch has not already been merged to the master branch. As a rule, bug |
| 229 | fixes should never be applied first to a stable branch. Patches should land |
| 230 | first on the master branch and then be cherry-picked to a stable |
| 231 | branch. (This is to avoid future releases causing regressions if the patch |
| 232 | is not also applied to master.) The only things that might look like |
| 233 | exceptions would be backports of patches from master that happen to look |
| 234 | significantly different.</li> |
| 235 | |
| 236 | <li>Patch depends on too many other patches. Ideally, all stable-branch |
| 237 | patches should be self-contained. It sometimes occurs that a single, logical |
| 238 | bug-fix occurs as two separate patches on master, (such as an original |
| 239 | patch, then a subsequent fix-up to that patch). In such a case, these two |
| 240 | patches should be squashed into a single, self-contained patch for the |
| 241 | stable branch. (Of course, if the squashing makes the patch too large, then |
| 242 | that could be a reason to reject the patch.)</li> |
| 243 | |
| 244 | <li>Patch includes new feature development, not bug fixes. New OpenGL |
| 245 | features, extensions, etc. should be applied to Mesa master and included in |
| 246 | the next major release. Stable releases are intended only for bug fixes. |
| 247 | |
| 248 | Note: As an exception to this rule, the stable-release manager may accept |
| 249 | hardware-enabling "features". For example, backports of new code to support |
| 250 | a newly-developed hardware product can be accepted if they can be reasonably |
| 251 | determined to not have effects on other hardware.</li> |
| 252 | |
| 253 | <li>Patch is a performance optimization. As a rule, performance patches are |
| 254 | not candidates for the stable branch. The only exception might be a case |
| 255 | where an application's performance was recently severely impacted so as to |
| 256 | become unusable. The fix for this performance regression could then be |
| 257 | considered for a stable branch. The optimization must also be |
| 258 | non-controversial and the patches still need to meet the other criteria of |
| 259 | being simple and self-contained</li> |
| 260 | |
| 261 | <li>Patch introduces a new failure mode (such as an assert). While the new |
| 262 | assert might technically be correct, for example to make Mesa more |
| 263 | conformant, this is not the kind of "bug fix" we want in a stable |
| 264 | release. The potential problem here is that an OpenGL program that was |
| 265 | previously working, (even if technically non-compliant with the |
| 266 | specification), could stop working after this patch. So that would be a |
| 267 | regression that is unaacceptable for the stable branch.</li> |
| 268 | </ul> |
Andreas Boll | 1f38fb2 | 2012-10-02 13:55:53 +0200 | [diff] [blame] | 269 | |
Brian Paul | 98f2f47 | 2015-05-25 09:13:09 -0600 | [diff] [blame^] | 270 | |
| 271 | <h2 id="release">Making a New Mesa Release</h2> |
Brian Paul | 0b27ace | 2003-03-08 17:38:57 +0000 | [diff] [blame] | 272 | |
| 273 | <p> |
| 274 | These are the instructions for making a new Mesa release. |
| 275 | </p> |
| 276 | |
Andreas Boll | 210a27d | 2012-06-12 09:05:36 +0200 | [diff] [blame] | 277 | <h3>Get latest source files</h3> |
Brian Paul | 0b27ace | 2003-03-08 17:38:57 +0000 | [diff] [blame] | 278 | <p> |
Brian Paul | 84c5e48 | 2009-06-23 19:21:04 -0600 | [diff] [blame] | 279 | Use git to get the latest Mesa files from the git repository, from whatever |
Carl Worth | 619505a | 2014-08-21 10:44:35 -0700 | [diff] [blame] | 280 | branch is relevant. This document uses the convention X.Y.Z for the release |
| 281 | being created, which should be created from a branch named X.Y. |
Brian Paul | 0b27ace | 2003-03-08 17:38:57 +0000 | [diff] [blame] | 282 | </p> |
| 283 | |
Carl Worth | 619505a | 2014-08-21 10:44:35 -0700 | [diff] [blame] | 284 | <h3>Perform basic testing</h3> |
Brian Paul | 65b7905 | 2004-11-22 17:49:15 +0000 | [diff] [blame] | 285 | <p> |
Carl Worth | 619505a | 2014-08-21 10:44:35 -0700 | [diff] [blame] | 286 | The release manager should, at the very least, test the code by compiling it, |
| 287 | installing it, and running the latest piglit to ensure that no piglit tests |
| 288 | have regressed since the previous release. |
Brian Paul | 65b7905 | 2004-11-22 17:49:15 +0000 | [diff] [blame] | 289 | </p> |
| 290 | |
| 291 | <p> |
Carl Worth | 619505a | 2014-08-21 10:44:35 -0700 | [diff] [blame] | 292 | The release manager should do this testing with at least one hardware driver, |
| 293 | (say, whatever is contained in the local development machine), as well as on |
| 294 | both Gallium and non-Gallium software drivers. The software testing can be |
| 295 | performed by running piglit with the following environment-variable set: |
Andreas Boll | b347bb5 | 2012-06-25 21:53:06 +0200 | [diff] [blame] | 296 | </p> |
| 297 | |
Brian Paul | 0b27ace | 2003-03-08 17:38:57 +0000 | [diff] [blame] | 298 | <pre> |
Carl Worth | 619505a | 2014-08-21 10:44:35 -0700 | [diff] [blame] | 299 | LIBGL_ALWAYS_SOFTWARE=1 |
| 300 | </pre> |
| 301 | |
| 302 | And Gallium vs. non-Gallium software drivers can be obtained by using the |
| 303 | following configure flags on separate builds: |
| 304 | |
| 305 | <pre> |
| 306 | --with-dri-drivers=swrast |
| 307 | --with-gallium-drivers=swrast |
Brian Paul | 0b27ace | 2003-03-08 17:38:57 +0000 | [diff] [blame] | 308 | </pre> |
| 309 | |
| 310 | <p> |
Carl Worth | 619505a | 2014-08-21 10:44:35 -0700 | [diff] [blame] | 311 | Note: If both options are given in one build, both swrast_dri.so drivers will |
| 312 | be compiled, but only one will be installed. The following command can be used |
| 313 | to ensure the correct driver is being tested: |
| 314 | </p> |
| 315 | |
| 316 | <pre> |
| 317 | LIBGL_ALWAYS_SOFTWARE=1 glxinfo | grep "renderer string" |
| 318 | </pre> |
| 319 | |
| 320 | If any regressions are found in this testing with piglit, stop here, and do |
| 321 | not perform a release until regressions are fixed. |
| 322 | |
| 323 | <h3>Update version in file VERSION</h3> |
| 324 | |
| 325 | <p> |
| 326 | Increment the version contained in the file VERSION at Mesa's top-level, then |
| 327 | commit this change. |
| 328 | </p> |
| 329 | |
| 330 | <h3>Create release notes for the new release</h3> |
| 331 | |
| 332 | <p> |
| 333 | Create a new file docs/relnotes/X.Y.Z.html, (follow the style of the previous |
| 334 | release notes). Note that the sha256sums section of the release notes should |
| 335 | be empty at this point. |
Brian Paul | 65b7905 | 2004-11-22 17:49:15 +0000 | [diff] [blame] | 336 | </p> |
| 337 | |
| 338 | <p> |
Carl Worth | 619505a | 2014-08-21 10:44:35 -0700 | [diff] [blame] | 339 | Two scripts are available to help generate portions of the release notes: |
Brian Paul | 0b27ace | 2003-03-08 17:38:57 +0000 | [diff] [blame] | 340 | |
Carl Worth | 619505a | 2014-08-21 10:44:35 -0700 | [diff] [blame] | 341 | <pre> |
| 342 | ./bin/bugzilla_mesa.sh |
| 343 | ./bin/shortlog_mesa.sh |
| 344 | </pre> |
| 345 | |
Brian Paul | 0b27ace | 2003-03-08 17:38:57 +0000 | [diff] [blame] | 346 | <p> |
Carl Worth | 619505a | 2014-08-21 10:44:35 -0700 | [diff] [blame] | 347 | The first script identifies commits that reference bugzilla bugs and obtains |
| 348 | the descriptions of those bugs from bugzilla. The second script generates a |
| 349 | log of all commits. In both cases, HTML-formatted lists are printed to stdout |
| 350 | to be included in the release notes. |
Brian Paul | 0b27ace | 2003-03-08 17:38:57 +0000 | [diff] [blame] | 351 | </p> |
| 352 | |
| 353 | <p> |
Carl Worth | 619505a | 2014-08-21 10:44:35 -0700 | [diff] [blame] | 354 | Commit these changes |
| 355 | </p> |
| 356 | |
| 357 | <h3>Make the release archives, signatures, and the release tag</h3> |
| 358 | <p> |
| 359 | From inside the Mesa directory: |
| 360 | <pre> |
| 361 | ./autogen.sh |
| 362 | make -j1 tarballs |
| 363 | </pre> |
| 364 | |
| 365 | <p> |
| 366 | After the tarballs are created, the sha256 checksums for the files will |
| 367 | be computed and printed. These will be used in a step below. |
| 368 | </p> |
| 369 | |
| 370 | <p> |
| 371 | It's important at this point to also verify that the constructed tar file |
| 372 | actually builds: |
| 373 | </p> |
| 374 | |
| 375 | <pre> |
| 376 | tar xjf MesaLib-X.Y.Z.tar.bz2 |
| 377 | cd Mesa-X.Y.Z |
| 378 | ./configure --enable-gallium-llvm |
| 379 | make -j6 |
| 380 | make install |
| 381 | </pre> |
| 382 | |
| 383 | <p> |
| 384 | Some touch testing should also be performed at this point, (run glxgears or |
| 385 | more involved OpenGL programs against the installed Mesa). |
| 386 | </p> |
| 387 | |
| 388 | <p> |
| 389 | Create detached GPG signatures for each of the archive files created above: |
| 390 | </p> |
| 391 | |
| 392 | <pre> |
| 393 | gpg --sign --detach MesaLib-X.Y.Z.tar.gz |
| 394 | gpg --sign --detach MesaLib-X.Y.Z.tar.bz2 |
| 395 | gpg --sign --detach MesaLib-X.Y.Z.zip |
| 396 | </pre> |
| 397 | |
| 398 | <p> |
| 399 | Tag the commit used for the build: |
| 400 | </p> |
| 401 | |
| 402 | <pre> |
| 403 | git tag -s mesa-X.Y.X -m "Mesa X.Y.Z release" |
| 404 | </pre> |
| 405 | |
| 406 | <p> |
| 407 | Note: It would be nice to investigate and fix the issue that causes the |
| 408 | tarballs target to fail with multiple build process, such as with "-j4". It |
| 409 | would also be nice to incorporate all of the above commands into a single |
| 410 | makefile target. And instead of a custom "tarballs" target, we should |
| 411 | incorporate things into the standard "make dist" and "make distcheck" targets. |
| 412 | </p> |
| 413 | |
| 414 | <h3>Add the sha256sums to the release notes</h3> |
| 415 | |
| 416 | <p> |
| 417 | Edit docs/relnotes/X.Y.Z.html to add the sha256sums printed as part of "make |
| 418 | tarballs" in the previous step. Commit this change. |
| 419 | </p> |
| 420 | |
| 421 | <h3>Push all commits and the tag creates above</h3> |
| 422 | |
| 423 | <p> |
| 424 | This is the first step that cannot easily be undone. The release is going |
| 425 | forward from this point: |
| 426 | </p> |
| 427 | |
| 428 | <pre> |
| 429 | git push origin X.Y --tags |
| 430 | </pre> |
| 431 | |
| 432 | <h3>Install the release files and signatures on the distribution server</h3> |
| 433 | |
| 434 | <p> |
| 435 | The following commands can be used to copy the release archive files and |
| 436 | signatures to the freedesktop.org server: |
| 437 | </p> |
| 438 | |
| 439 | <pre> |
| 440 | scp MesaLib-X.Y.Z* people.freedesktop.org: |
| 441 | ssh people.freedesktop.org |
| 442 | cd /srv/ftp.freedesktop.org/pub/mesa |
| 443 | mkdir X.Y.Z |
| 444 | cd X.Y.Z |
| 445 | mv ~/MesaLib-X.Y.Z* . |
| 446 | </pre> |
| 447 | |
| 448 | <h3>Back on mesa master, andd the new release notes into the tree</h3> |
| 449 | |
| 450 | <p> |
| 451 | Something like the following steps will do the trick: |
| 452 | </p> |
| 453 | |
| 454 | <pre> |
| 455 | cp docs/relnotes/X.Y.Z.html /tmp |
| 456 | git checkout master |
| 457 | cp /tmp/X.Y.Z.html docs/relnotes |
| 458 | git add docs/relnotes/X.Y.Z.html |
| 459 | </pre> |
| 460 | |
| 461 | <p> |
| 462 | Also, edit docs/relnotes.html to add a link to the new release notes, and edit |
| 463 | docs/index.html to add a news entry. Then commit and push: |
| 464 | </p> |
| 465 | |
| 466 | <pre> |
| 467 | git commit -a -m "docs: Import X.Y.Z release notes, add news item." |
| 468 | git push origin |
| 469 | </pre> |
| 470 | |
| 471 | <h3>Update the mesa3d.org website</h3> |
| 472 | |
| 473 | <p> |
| 474 | NOTE: The recent release managers have not been performing this step |
| 475 | themselves, but leaving this to Brian Paul, (who has access to the |
| 476 | sourceforge.net hosting for mesa3d.org). Brian is more than willing to grant |
| 477 | the permission necessary to future release managers to do this step on their |
| 478 | own. |
Brian Paul | 84c5e48 | 2009-06-23 19:21:04 -0600 | [diff] [blame] | 479 | </p> |
| 480 | |
| 481 | <p> |
Brian Paul | 65b7905 | 2004-11-22 17:49:15 +0000 | [diff] [blame] | 482 | Update the web site by copying the docs/ directory's files to |
Brian Paul | 84c5e48 | 2009-06-23 19:21:04 -0600 | [diff] [blame] | 483 | /home/users/b/br/brianp/mesa-www/htdocs/ with: |
| 484 | <br> |
| 485 | <code> |
| 486 | sftp USERNAME,mesa3d@web.sourceforge.net |
| 487 | </code> |
Brian Paul | 0b27ace | 2003-03-08 17:38:57 +0000 | [diff] [blame] | 488 | </p> |
| 489 | |
Carl Worth | 619505a | 2014-08-21 10:44:35 -0700 | [diff] [blame] | 490 | |
| 491 | <h3>Announce the release</h3> |
Brian Paul | 0b27ace | 2003-03-08 17:38:57 +0000 | [diff] [blame] | 492 | <p> |
Brian Paul | efe5671 | 2003-03-19 19:15:28 +0000 | [diff] [blame] | 493 | Make an announcement on the mailing lists: |
Ian Romanick | 8f32c64 | 2010-06-16 14:28:08 -0700 | [diff] [blame] | 494 | |
Kenneth Graunke | 7d24d1b | 2013-07-25 11:42:38 -0700 | [diff] [blame] | 495 | <em>mesa-dev@lists.freedesktop.org</em>, |
Brian Paul | efe5671 | 2003-03-19 19:15:28 +0000 | [diff] [blame] | 496 | and |
Kenneth Graunke | 7d24d1b | 2013-07-25 11:42:38 -0700 | [diff] [blame] | 497 | <em>mesa-announce@lists.freedesktop.org</em> |
Carl Worth | 619505a | 2014-08-21 10:44:35 -0700 | [diff] [blame] | 498 | |
| 499 | Follow the template of previously-sent release announcements. The following |
| 500 | command can be used to generate the log of changes to be included in the |
| 501 | release announcement: |
| 502 | |
| 503 | <pre> |
| 504 | git shortlog mesa-X.Y.Z-1..mesa-X.Y.Z |
| 505 | </pre> |
Brian Paul | 0b27ace | 2003-03-08 17:38:57 +0000 | [diff] [blame] | 506 | </p> |
| 507 | |
Brian Paul | 98f2f47 | 2015-05-25 09:13:09 -0600 | [diff] [blame^] | 508 | |
| 509 | <h2 id="extensions">Adding Extensions</h2> |
| 510 | |
| 511 | <p> |
| 512 | To add a new GL extension to Mesa you have to do at least the following. |
| 513 | |
| 514 | <ul> |
| 515 | <li> |
| 516 | If glext.h doesn't define the extension, edit include/GL/gl.h and add |
| 517 | code like this: |
| 518 | <pre> |
| 519 | #ifndef GL_EXT_the_extension_name |
| 520 | #define GL_EXT_the_extension_name 1 |
| 521 | /* declare the new enum tokens */ |
| 522 | /* prototype the new functions */ |
| 523 | /* TYPEDEFS for the new functions */ |
| 524 | #endif |
| 525 | </pre> |
| 526 | </li> |
| 527 | <li> |
| 528 | In the src/mapi/glapi/gen/ directory, add the new extension functions and |
| 529 | enums to the gl_API.xml file. |
| 530 | Then, a bunch of source files must be regenerated by executing the |
| 531 | corresponding Python scripts. |
| 532 | </li> |
| 533 | <li> |
| 534 | Add a new entry to the <code>gl_extensions</code> struct in mtypes.h |
| 535 | </li> |
| 536 | <li> |
| 537 | Update the <code>extensions.c</code> file. |
| 538 | </li> |
| 539 | <li> |
| 540 | From this point, the best way to proceed is to find another extension, |
| 541 | similar to the new one, that's already implemented in Mesa and use it |
| 542 | as an example. |
| 543 | </li> |
| 544 | <li> |
| 545 | If the new extension adds new GL state, the functions in get.c, enable.c |
| 546 | and attrib.c will most likely require new code. |
| 547 | </li> |
| 548 | <li> |
| 549 | The dispatch tests check_table.cpp and dispatch_sanity.cpp |
| 550 | should be updated with details about the new extensions functions. These |
| 551 | tests are run using 'make check' |
| 552 | </li> |
| 553 | </ul> |
| 554 | |
| 555 | |
| 556 | |
| 557 | |
Andreas Boll | b5da52a | 2012-09-18 18:57:02 +0200 | [diff] [blame] | 558 | </div> |
Brian Paul | 0b27ace | 2003-03-08 17:38:57 +0000 | [diff] [blame] | 559 | </body> |
| 560 | </html> |