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