| 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>Submitting patches</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>Submitting patches</h1>
|
|---|
| 18 |
|
|---|
| 19 |
|
|---|
| 20 | <ul>
|
|---|
| 21 | <li><a href="#guidelines">Basic guidelines</a>
|
|---|
| 22 | <li><a href="#formatting">Patch formatting</a>
|
|---|
| 23 | <li><a href="#testing">Testing Patches</a>
|
|---|
| 24 | <li><a href="#mailing">Mailing Patches</a>
|
|---|
| 25 | <li><a href="#reviewing">Reviewing Patches</a>
|
|---|
| 26 | <li><a href="#nominations">Nominating a commit for a stable branch</a>
|
|---|
| 27 | <li><a href="#criteria">Criteria for accepting patches to the stable branch</a>
|
|---|
| 28 | <li><a href="#backports">Sending backports for the stable branch</a>
|
|---|
| 29 | <li><a href="#gittips">Git tips</a>
|
|---|
| 30 | </ul>
|
|---|
| 31 |
|
|---|
| 32 | <h2 id="guidelines">Basic guidelines</h2>
|
|---|
| 33 |
|
|---|
| 34 | <ul>
|
|---|
| 35 | <li>Patches should not mix code changes with code formatting changes (except,
|
|---|
| 36 | perhaps, in very trivial cases.)
|
|---|
| 37 | <li>Code patches should follow Mesa
|
|---|
| 38 | <a href="codingstyle.html" target="_parent">coding conventions</a>.
|
|---|
| 39 | <li>Whenever possible, patches should only effect individual Mesa/Gallium
|
|---|
| 40 | components.
|
|---|
| 41 | <li>Patches should never introduce build breaks and should be bisectable (see
|
|---|
| 42 | <code>git bisect</code>.)
|
|---|
| 43 | <li>Patches should be properly <a href="#formatting">formatted</a>.
|
|---|
| 44 | <li>Patches should be sufficiently <a href="#testing">tested</a> before submitting.
|
|---|
| 45 | <li>Patches should be submitted to <a href="#mailing">mesa-dev</a>
|
|---|
| 46 | for <a href="#reviewing">review</a> using <code>git send-email</code>.
|
|---|
| 47 |
|
|---|
| 48 | </ul>
|
|---|
| 49 |
|
|---|
| 50 | <h2 id="formatting">Patch formatting</h2>
|
|---|
| 51 |
|
|---|
| 52 | <ul>
|
|---|
| 53 | <li>Lines should be limited to 75 characters or less so that git logs
|
|---|
| 54 | displayed in 80-column terminals avoid line wrapping. Note that git
|
|---|
| 55 | log uses 4 spaces of indentation (4 + 75 < 80).
|
|---|
| 56 | <li>The first line should be a short, concise summary of the change prefixed
|
|---|
| 57 | with a module name. Examples:
|
|---|
| 58 | <pre>
|
|---|
| 59 | mesa: Add support for querying GL_VERTEX_ATTRIB_ARRAY_LONG
|
|---|
| 60 |
|
|---|
| 61 | gallium: add PIPE_CAP_DEVICE_RESET_STATUS_QUERY
|
|---|
| 62 |
|
|---|
| 63 | i965: Fix missing type in local variable declaration.
|
|---|
| 64 | </pre>
|
|---|
| 65 | <li>Subsequent patch comments should describe the change in more detail,
|
|---|
| 66 | if needed. For example:
|
|---|
| 67 | <pre>
|
|---|
| 68 | i965: Remove end-of-thread SEND alignment code.
|
|---|
| 69 |
|
|---|
| 70 | This was present in Eric's initial implementation of the compaction code
|
|---|
| 71 | for Sandybridge (commit 077d01b6). There is no documentation saying this
|
|---|
| 72 | is necessary, and removing it causes no regressions in piglit on any
|
|---|
| 73 | platform.
|
|---|
| 74 | </pre>
|
|---|
| 75 | <li>A "Signed-off-by:" line is not required, but not discouraged either.
|
|---|
| 76 | <li>If a patch addresses a bugzilla issue, that should be noted in the
|
|---|
| 77 | patch comment. For example:
|
|---|
| 78 | <pre>
|
|---|
| 79 | Bugzilla: https://bugs.freedesktop.org/show_bug.cgi?id=89689
|
|---|
| 80 | </pre>
|
|---|
| 81 | <li>If a patch addresses a issue introduced with earlier commit, that should be
|
|---|
| 82 | noted in the patch comment. For example:
|
|---|
| 83 | <pre>
|
|---|
| 84 | Fixes: d7b3707c612 "util/disk_cache: use stat() to check if entry is a directory"
|
|---|
| 85 | </pre>
|
|---|
| 86 | <li>If there have been several revisions to a patch during the review
|
|---|
| 87 | process, they should be noted such as in this example:
|
|---|
| 88 | <pre>
|
|---|
| 89 | st/mesa: add ARB_texture_stencil8 support (v4)
|
|---|
| 90 |
|
|---|
| 91 | if we support stencil texturing, enable texture_stencil8
|
|---|
| 92 | there is no requirement to support native S8 for this,
|
|---|
| 93 | the texture can be converted to x24s8 fine.
|
|---|
| 94 |
|
|---|
| 95 | v2: fold fixes from Marek in:
|
|---|
| 96 | a) put S8 last in the list
|
|---|
| 97 | b) fix renderable to always test for d/s renderable
|
|---|
| 98 | fixup the texture case to use a stencil only format
|
|---|
| 99 | for picking the format for the texture view.
|
|---|
| 100 | v3: hit fallback for getteximage
|
|---|
| 101 | v4: put s8 back in front, it shouldn't get picked now (Ilia)
|
|---|
| 102 | </pre>
|
|---|
| 103 | <li>If someone tested your patch, document it with a line like this:
|
|---|
| 104 | <pre>
|
|---|
| 105 | Tested-by: Joe Hacker <[email protected]>
|
|---|
| 106 | </pre>
|
|---|
| 107 | <li>If the patch was reviewed (usually the case) or acked by someone,
|
|---|
| 108 | that should be documented with:
|
|---|
| 109 | <pre>
|
|---|
| 110 | Reviewed-by: Joe Hacker <[email protected]>
|
|---|
| 111 | Acked-by: Joe Hacker <[email protected]>
|
|---|
| 112 | </pre>
|
|---|
| 113 | <li>If sending later revision of a patch, add all the tags - ack, r-b,
|
|---|
| 114 | Cc: mesa-stable and/or other. This provides reviewers with quick feedback if the
|
|---|
| 115 | patch has already been reviewed.
|
|---|
| 116 | <li>In order for your patch to reach the prospective reviewer easier/faster,
|
|---|
| 117 | use the script scripts/get_reviewer.pl to get a list of individuals and include
|
|---|
| 118 | them in the CC list.
|
|---|
| 119 | <br>
|
|---|
| 120 | Please use common sense and do <strong>not</strong> blindly add everyone.
|
|---|
| 121 | <br>
|
|---|
| 122 | <pre>
|
|---|
| 123 | $ scripts/get_reviewer.pl --help # to get the help screen
|
|---|
| 124 | $ scripts/get_reviewer.pl -f src/egl/drivers/dri2/platform_android.c
|
|---|
| 125 | Rob Herring <robh@kernel.org> (reviewer:ANDROID EGL SUPPORT,added_lines:188/700=27%,removed_lines:58/283=20%)
|
|---|
| 126 | Tomasz Figa <tfiga@chromium.org> (reviewer:ANDROID EGL SUPPORT,authored:12/41=29%,added_lines:308/700=44%,removed_lines:115/283=41%)
|
|---|
| 127 | Emil Velikov <emil.l.velikov@gmail.com> (authored:13/41=32%,removed_lines:76/283=27%)
|
|---|
| 128 | </pre>
|
|---|
| 129 | </ul>
|
|---|
| 130 |
|
|---|
| 131 |
|
|---|
| 132 |
|
|---|
| 133 | <h2 id="testing">Testing Patches</h2>
|
|---|
| 134 |
|
|---|
| 135 | <p>
|
|---|
| 136 | It should go without saying that patches must be tested. In general,
|
|---|
| 137 | do whatever testing is prudent.
|
|---|
| 138 | </p>
|
|---|
| 139 |
|
|---|
| 140 | <p>
|
|---|
| 141 | You should always run the Mesa test suite before submitting patches.
|
|---|
| 142 | The test suite can be run using the 'make check' command. All tests
|
|---|
| 143 | must pass before patches will be accepted, this may mean you have
|
|---|
| 144 | to update the tests themselves.
|
|---|
| 145 | </p>
|
|---|
| 146 |
|
|---|
| 147 | <p>
|
|---|
| 148 | Whenever possible and applicable, test the patch with
|
|---|
| 149 | <a href="https://piglit.freedesktop.org">Piglit</a> and/or
|
|---|
| 150 | <a href="https://android.googlesource.com/platform/external/deqp/">dEQP</a>
|
|---|
| 151 | to check for regressions.
|
|---|
| 152 | </p>
|
|---|
| 153 |
|
|---|
| 154 | <p>
|
|---|
| 155 | As mentioned at the begining, patches should be bisectable.
|
|---|
| 156 | A good way to test this is to make use of the `git rebase` command,
|
|---|
| 157 | to run your tests on each commit. Assuming your branch is based off
|
|---|
| 158 | <code>origin/master</code>, you can run:
|
|---|
| 159 | <pre>
|
|---|
| 160 | $ git rebase --interactive --exec "make check" origin/master
|
|---|
| 161 | </pre>
|
|---|
| 162 | replacing <code>"make check"</code> with whatever other test you want to
|
|---|
| 163 | run.
|
|---|
| 164 | </p>
|
|---|
| 165 |
|
|---|
| 166 |
|
|---|
| 167 | <h2 id="mailing">Mailing Patches</h2>
|
|---|
| 168 |
|
|---|
| 169 | <p>
|
|---|
| 170 | Patches should be sent to the mesa-dev mailing list for review:
|
|---|
| 171 | <a href="https://lists.freedesktop.org/mailman/listinfo/mesa-dev">
|
|---|
| 172 | [email protected]</a>.
|
|---|
| 173 | When submitting a patch make sure to use
|
|---|
| 174 | <a href="https://git-scm.com/docs/git-send-email">git send-email</a>
|
|---|
| 175 | rather than attaching patches to emails. Sending patches as
|
|---|
| 176 | attachments prevents people from being able to provide in-line review
|
|---|
| 177 | comments.
|
|---|
| 178 | </p>
|
|---|
| 179 |
|
|---|
| 180 | <p>
|
|---|
| 181 | When submitting follow-up patches you can use --in-reply-to to make v2, v3,
|
|---|
| 182 | etc patches show up as replies to the originals. This usually works well
|
|---|
| 183 | when you're sending out updates to individual patches (as opposed to
|
|---|
| 184 | re-sending the whole series). Using --in-reply-to makes
|
|---|
| 185 | it harder for reviewers to accidentally review old patches.
|
|---|
| 186 | </p>
|
|---|
| 187 |
|
|---|
| 188 | <p>
|
|---|
| 189 | When submitting follow-up patches you should also login to
|
|---|
| 190 | <a href="https://patchwork.freedesktop.org">patchwork</a> and change the
|
|---|
| 191 | state of your old patches to Superseded.
|
|---|
| 192 | </p>
|
|---|
| 193 |
|
|---|
| 194 | <p>
|
|---|
| 195 | Some companies' mail server automatically append a legal disclaimer,
|
|---|
| 196 | usually containing something along the lines of "The information in this
|
|---|
| 197 | email is confidential" and "distribution is strictly prohibited".<br/>
|
|---|
| 198 | These legal notices prevent us from being able to accept your patch,
|
|---|
| 199 | rendering the whole process pointless. Please make sure these are
|
|---|
| 200 | disabled before sending your patches. (Note that you may need to contact
|
|---|
| 201 | your email administrator for this.)
|
|---|
| 202 | </p>
|
|---|
| 203 |
|
|---|
| 204 | <h2 id="reviewing">Reviewing Patches</h2>
|
|---|
| 205 |
|
|---|
| 206 | <p>
|
|---|
| 207 | When you've reviewed a patch on the mailing list, please be unambiguous
|
|---|
| 208 | about your review. That is, state either
|
|---|
| 209 | </p>
|
|---|
| 210 | <pre>
|
|---|
| 211 | Reviewed-by: Joe Hacker <[email protected]>
|
|---|
| 212 | </pre>
|
|---|
| 213 | or
|
|---|
| 214 | <pre>
|
|---|
| 215 | Acked-by: Joe Hacker <[email protected]>
|
|---|
| 216 | </pre>
|
|---|
| 217 | <p>
|
|---|
| 218 | Rather than saying just "LGTM" or "Seems OK".
|
|---|
| 219 | </p>
|
|---|
| 220 |
|
|---|
| 221 | <p>
|
|---|
| 222 | If small changes are suggested, it's OK to say something like:
|
|---|
| 223 | </p>
|
|---|
| 224 | <pre>
|
|---|
| 225 | With the above fixes, Reviewed-by: Joe Hacker <[email protected]>
|
|---|
| 226 | </pre>
|
|---|
| 227 | <p>
|
|---|
| 228 | which tells the patch author that the patch can be committed, as long
|
|---|
| 229 | as the issues are resolved first.
|
|---|
| 230 | </p>
|
|---|
| 231 |
|
|---|
| 232 |
|
|---|
| 233 | <h2 id="nominations">Nominating a commit for a stable branch</h2>
|
|---|
| 234 |
|
|---|
| 235 | <p>
|
|---|
| 236 | There are three ways to nominate a patch for inclusion in the stable branch and
|
|---|
| 237 | release.
|
|---|
| 238 | </p>
|
|---|
| 239 | <ul>
|
|---|
| 240 | <li> By adding the Cc: mesa-stable@ tag as described below.
|
|---|
| 241 | <li> Sending the commit ID (as seen in master branch) to the mesa-stable@ mailing list.
|
|---|
| 242 | <li> Forwarding the patch from the mesa-dev@ mailing list.
|
|---|
| 243 | </li>
|
|---|
| 244 | </ul>
|
|---|
| 245 | <p>
|
|---|
| 246 | Note: resending patch identical to one on mesa-dev@ or one that differs only
|
|---|
| 247 | by the extra mesa-stable@ tag is <strong>not</strong> recommended.
|
|---|
| 248 | </p>
|
|---|
| 249 |
|
|---|
| 250 |
|
|---|
| 251 | <h3 id="thetag">The stable tag</h3>
|
|---|
| 252 |
|
|---|
| 253 | <p>
|
|---|
| 254 | If you want a commit to be applied to a stable branch,
|
|---|
| 255 | you should add an appropriate note to the commit message.
|
|---|
| 256 | </p>
|
|---|
| 257 |
|
|---|
| 258 | <p>
|
|---|
| 259 | Here are some examples of such a note:
|
|---|
| 260 | </p>
|
|---|
| 261 | <ul>
|
|---|
| 262 | <li>CC: <[email protected]></li>
|
|---|
| 263 | </ul>
|
|---|
| 264 |
|
|---|
| 265 | Simply adding the CC to the mesa-stable list address is adequate to nominate
|
|---|
| 266 | the commit for all the active stable branches. If the commit is not applicable
|
|---|
| 267 | for said branch the stable-release manager will reply stating so.
|
|---|
| 268 |
|
|---|
| 269 | This "CC" syntax for patch nomination will cause patches to automatically be
|
|---|
| 270 | copied to the mesa-stable@ mailing list when you use "git send-email" to send
|
|---|
| 271 | patches to the mesa-dev@ mailing list. If you prefer using --suppress-cc that
|
|---|
| 272 | won't have any negative effect on the patch nomination.
|
|---|
| 273 |
|
|---|
| 274 | <p>
|
|---|
| 275 | Note: by removing the tag [as the commit is pushed] the patch is
|
|---|
| 276 | <strong>explicitly</strong> rejected from inclusion in the stable branch(es).
|
|---|
| 277 | <br>
|
|---|
| 278 | Thus, drop the line <strong>only</strong> if you want to cancel the nomination.
|
|---|
| 279 | </p>
|
|---|
| 280 |
|
|---|
| 281 | Alternatively, if one uses the "Fixes" tag as described in the "Patch formatting"
|
|---|
| 282 | section, it nominates a commit for all active stable branches that include the
|
|---|
| 283 | commit that is referred to.
|
|---|
| 284 |
|
|---|
| 285 | <h2 id="criteria">Criteria for accepting patches to the stable branch</h2>
|
|---|
| 286 |
|
|---|
| 287 | Mesa has a designated release manager for each stable branch, and the release
|
|---|
| 288 | manager is the only developer that should be pushing changes to these branches.
|
|---|
| 289 | Everyone else should nominate patches using the mechanism described above.
|
|---|
| 290 |
|
|---|
| 291 | The following rules define which patches are accepted and which are not. The
|
|---|
| 292 | stable-release manager is also given broad discretion in rejecting patches
|
|---|
| 293 | that have been nominated.
|
|---|
| 294 |
|
|---|
| 295 | <ul>
|
|---|
| 296 | <li>Patch must conform with the <a href="#guidelines">Basic guidelines</a></li>
|
|---|
| 297 |
|
|---|
| 298 | <li>Patch must have landed in master first. In case where the original
|
|---|
| 299 | patch is too large and/or otherwise contradicts with the rules set within, a
|
|---|
| 300 | backport is appropriate.</li>
|
|---|
| 301 |
|
|---|
| 302 | <li>It must not introduce a regression - be that build or runtime wise.
|
|---|
| 303 |
|
|---|
| 304 | Note: If the regression is due to faulty piglit/dEQP/CTS/other test the
|
|---|
| 305 | latter must be fixed first. A reference to the offending test(s) and
|
|---|
| 306 | respective fix(es) should be provided in the nominated patch.</li>
|
|---|
| 307 |
|
|---|
| 308 | <li>Patch cannot be larger than 100 lines.</li>
|
|---|
| 309 |
|
|---|
| 310 | <li>Patches that move code around with no functional change should be
|
|---|
| 311 | rejected.</li>
|
|---|
| 312 |
|
|---|
| 313 | <li>Patch must be a bug fix and not a new feature.
|
|---|
| 314 |
|
|---|
| 315 | Note: An exception to this rule, are hardware-enabling "features". For
|
|---|
| 316 | example, <a href="#backports">backports</a> of new code to support a
|
|---|
| 317 | newly-developed hardware product can be accepted if they can be reasonably
|
|---|
| 318 | determined not to have effects on other hardware.</li>
|
|---|
| 319 |
|
|---|
| 320 | <li>Patch must be reviewed, For example, the commit message has Reviewed-by,
|
|---|
| 321 | Signed-off-by, or Tested-by tags from someone but the author.</li>
|
|---|
| 322 |
|
|---|
| 323 | <li>Performance patches are considered only if they provide information
|
|---|
| 324 | about the hardware, program in question and observed improvement. Use numbers
|
|---|
| 325 | to represent your measurements.</li>
|
|---|
| 326 | </ul>
|
|---|
| 327 |
|
|---|
| 328 | If the patch complies with the rules it will be
|
|---|
| 329 | <a href="releasing.html#pickntest">cherry-picked</a>. Alternatively the release
|
|---|
| 330 | manager will reply to the patch in question stating why the patch has been
|
|---|
| 331 | rejected or would request a backport.
|
|---|
| 332 |
|
|---|
| 333 | A summary of all the picked/rejected patches will be presented in the
|
|---|
| 334 | <a href="releasing.html#prerelease">pre-release</a> announcement.
|
|---|
| 335 |
|
|---|
| 336 | The stable-release manager may at times need to force-push changes to the
|
|---|
| 337 | stable branches, for example, to drop a previously-picked patch that was later
|
|---|
| 338 | identified as causing a regression). These force-pushes may cause changes to
|
|---|
| 339 | be lost from the stable branch if developers push things directly. Consider
|
|---|
| 340 | yourself warned.
|
|---|
| 341 |
|
|---|
| 342 | <h2 id="backports">Sending backports for the stable branch</h2>
|
|---|
| 343 | By default merge conflicts are resolved by the stable-release manager. In which
|
|---|
| 344 | case he/she should provide a comment about the changes required, alongside the
|
|---|
| 345 | <code>Conflicts</code> section. Summary of which will be provided in the
|
|---|
| 346 | <a href="releasing.html#prerelease">pre-release</a> announcement.
|
|---|
| 347 | <br>
|
|---|
| 348 | Developers are interested in sending backports are recommended to use either a
|
|---|
| 349 | <code>[BACKPORT #branch]</code> subject prefix or provides similar information
|
|---|
| 350 | within the commit summary.
|
|---|
| 351 |
|
|---|
| 352 | <h2 id="gittips">Git tips</h2>
|
|---|
| 353 |
|
|---|
| 354 | <ul>
|
|---|
| 355 | <li><code>git rebase -i ...</code> is your friend. Don't be afraid to use it.
|
|---|
| 356 | <li>Apply a fixup to commit FOO.
|
|---|
| 357 | <pre>
|
|---|
| 358 | git add ...
|
|---|
| 359 | git commit --fixup=FOO
|
|---|
| 360 | git rebase -i --autosquash ...
|
|---|
| 361 | </pre>
|
|---|
| 362 | <li>Test for build breakage between patches e.g last 8 commits.
|
|---|
| 363 | <pre>
|
|---|
| 364 | git rebase -i --exec="make -j4" HEAD~8
|
|---|
| 365 | </pre>
|
|---|
| 366 | <li>Sets the default mailing address for your repo.
|
|---|
| 367 | <pre>
|
|---|
| 368 | git config --local sendemail.to [email protected]
|
|---|
| 369 | </pre>
|
|---|
| 370 | <li> Add version to subject line of patch series in this case for the last 8
|
|---|
| 371 | commits before sending.
|
|---|
| 372 | <pre>
|
|---|
| 373 | git send-email --subject-prefix="PATCH v4" HEAD~8
|
|---|
| 374 | git send-email -v4 @~8 # shorter version, inherited from git format-patch
|
|---|
| 375 | </pre>
|
|---|
| 376 | <li> Configure git to use the get_reviewer.pl script interactively. Thus you
|
|---|
| 377 | can avoid adding the world to the CC list.
|
|---|
| 378 | <pre>
|
|---|
| 379 | git config sendemail.cccmd "./scripts/get_reviewer.pl -i"
|
|---|
| 380 | </pre>
|
|---|
| 381 | </ul>
|
|---|
| 382 |
|
|---|
| 383 |
|
|---|
| 384 | </div>
|
|---|
| 385 | </body>
|
|---|
| 386 | </html>
|
|---|
