Emil Velikov | 259e65c | 2016-11-16 00:20:56 +0000 | [diff] [blame] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| 2 | <html lang="en"> |
| 3 | <head> |
| 4 | <meta http-equiv="content-type" content="text/html; charset=utf-8"> |
| 5 | <title>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> |
Timothy Arceri | e260bfe | 2016-11-21 16:30:12 +0000 | [diff] [blame] | 28 | <li><a href="#gittips">Git tips</a> |
Emil Velikov | 259e65c | 2016-11-16 00:20:56 +0000 | [diff] [blame] | 29 | </ul> |
| 30 | |
| 31 | <h2 id="guidelines">Basic guidelines</h2> |
| 32 | |
| 33 | <ul> |
| 34 | <li>Patches should not mix code changes with code formatting changes (except, |
| 35 | perhaps, in very trivial cases.) |
| 36 | <li>Code patches should follow Mesa |
| 37 | <a href="codingstyle.html" target="_parent">coding conventions</a>. |
| 38 | <li>Whenever possible, patches should only effect individual Mesa/Gallium |
| 39 | components. |
| 40 | <li>Patches should never introduce build breaks and should be bisectable (see |
| 41 | <code>git bisect</code>.) |
| 42 | <li>Patches should be properly <a href="#formatting">formatted</a>. |
| 43 | <li>Patches should be sufficiently <a href="#testing">tested</a> before submitting. |
Andres Gomez | 28158c3 | 2016-11-28 18:47:42 +0200 | [diff] [blame] | 44 | <li>Patches should be submitted to <a href="#mailing">mesa-dev</a> |
Emil Velikov | 259e65c | 2016-11-16 00:20:56 +0000 | [diff] [blame] | 45 | for <a href="#reviewing">review</a> using <code>git send-email</code>. |
| 46 | |
| 47 | </ul> |
| 48 | |
| 49 | <h2 id="formatting">Patch formatting</h2> |
| 50 | |
| 51 | <ul> |
| 52 | <li>Lines should be limited to 75 characters or less so that git logs |
| 53 | displayed in 80-column terminals avoid line wrapping. Note that git |
| 54 | log uses 4 spaces of indentation (4 + 75 < 80). |
| 55 | <li>The first line should be a short, concise summary of the change prefixed |
| 56 | with a module name. Examples: |
| 57 | <pre> |
| 58 | mesa: Add support for querying GL_VERTEX_ATTRIB_ARRAY_LONG |
| 59 | |
| 60 | gallium: add PIPE_CAP_DEVICE_RESET_STATUS_QUERY |
| 61 | |
| 62 | i965: Fix missing type in local variable declaration. |
| 63 | </pre> |
| 64 | <li>Subsequent patch comments should describe the change in more detail, |
| 65 | if needed. For example: |
| 66 | <pre> |
| 67 | i965: Remove end-of-thread SEND alignment code. |
| 68 | |
| 69 | This was present in Eric's initial implementation of the compaction code |
| 70 | for Sandybridge (commit 077d01b6). There is no documentation saying this |
| 71 | is necessary, and removing it causes no regressions in piglit on any |
| 72 | platform. |
| 73 | </pre> |
| 74 | <li>A "Signed-off-by:" line is not required, but not discouraged either. |
| 75 | <li>If a patch address a bugzilla issue, that should be noted in the |
| 76 | patch comment. For example: |
| 77 | <pre> |
| 78 | Bugzilla: https://bugs.freedesktop.org/show_bug.cgi?id=89689 |
| 79 | </pre> |
| 80 | <li>If there have been several revisions to a patch during the review |
| 81 | process, they should be noted such as in this example: |
| 82 | <pre> |
| 83 | st/mesa: add ARB_texture_stencil8 support (v4) |
| 84 | |
| 85 | if we support stencil texturing, enable texture_stencil8 |
| 86 | there is no requirement to support native S8 for this, |
| 87 | the texture can be converted to x24s8 fine. |
| 88 | |
| 89 | v2: fold fixes from Marek in: |
| 90 | a) put S8 last in the list |
| 91 | b) fix renderable to always test for d/s renderable |
| 92 | fixup the texture case to use a stencil only format |
| 93 | for picking the format for the texture view. |
| 94 | v3: hit fallback for getteximage |
| 95 | v4: put s8 back in front, it shouldn't get picked now (Ilia) |
| 96 | </pre> |
| 97 | <li>If someone tested your patch, document it with a line like this: |
| 98 | <pre> |
| 99 | Tested-by: Joe Hacker <jhacker@foo.com> |
| 100 | </pre> |
| 101 | <li>If the patch was reviewed (usually the case) or acked by someone, |
| 102 | that should be documented with: |
| 103 | <pre> |
| 104 | Reviewed-by: Joe Hacker <jhacker@foo.com> |
| 105 | Acked-by: Joe Hacker <jhacker@foo.com> |
| 106 | </pre> |
George Kyriazis | ba28f21 | 2016-11-28 17:35:26 +0000 | [diff] [blame] | 107 | <li>If sending later revision of a patch, add all the tags - ack, r-b, |
Eric Engestrom | fae5e1d | 2016-11-29 11:40:55 +0000 | [diff] [blame] | 108 | Cc: mesa-stable and/or other. This provides reviewers with quick feedback if the |
George Kyriazis | ba28f21 | 2016-11-28 17:35:26 +0000 | [diff] [blame] | 109 | patch has already been reviewed. |
Emil Velikov | a2283b5 | 2016-11-21 17:53:33 +0000 | [diff] [blame] | 110 | <li>In order for your patch to reach the prospective reviewer easier/faster, |
| 111 | use the script scripts/get_reviewer.pl to get a list of individuals and include |
| 112 | them in the CC list. |
| 113 | <br> |
| 114 | Please use common sense and do <strong>not</strong> blindly add everyone. |
| 115 | <br> |
| 116 | <pre> |
| 117 | $ scripts/get_reviewer.pl --help # to get the the help screen |
| 118 | $ scripts/get_reviewer.pl -f src/egl/drivers/dri2/platform_android.c |
| 119 | Rob Herring <robh@kernel.org> (reviewer:ANDROID EGL SUPPORT,added_lines:188/700=27%,removed_lines:58/283=20%) |
| 120 | Tomasz Figa <tfiga@chromium.org> (reviewer:ANDROID EGL SUPPORT,authored:12/41=29%,added_lines:308/700=44%,removed_lines:115/283=41%) |
| 121 | Emil Velikov <emil.l.velikov@gmail.com> (authored:13/41=32%,removed_lines:76/283=27%) |
| 122 | </pre> |
Emil Velikov | 259e65c | 2016-11-16 00:20:56 +0000 | [diff] [blame] | 123 | </ul> |
| 124 | |
| 125 | |
| 126 | |
| 127 | <h2 id="testing">Testing Patches</h2> |
| 128 | |
| 129 | <p> |
| 130 | It should go without saying that patches must be tested. In general, |
| 131 | do whatever testing is prudent. |
| 132 | </p> |
| 133 | |
| 134 | <p> |
| 135 | You should always run the Mesa test suite before submitting patches. |
| 136 | The test suite can be run using the 'make check' command. All tests |
| 137 | must pass before patches will be accepted, this may mean you have |
| 138 | to update the tests themselves. |
| 139 | </p> |
| 140 | |
| 141 | <p> |
| 142 | Whenever possible and applicable, test the patch with |
| 143 | <a href="http://piglit.freedesktop.org">Piglit</a> and/or |
| 144 | <a href="https://android.googlesource.com/platform/external/deqp/">dEQP</a> |
| 145 | to check for regressions. |
| 146 | </p> |
| 147 | |
| 148 | |
| 149 | <h2 id="mailing">Mailing Patches</h2> |
| 150 | |
| 151 | <p> |
| 152 | Patches should be sent to the mesa-dev mailing list for review: |
| 153 | <a href="https://lists.freedesktop.org/mailman/listinfo/mesa-dev"> |
Emil Velikov | b571c07 | 2016-11-16 11:54:54 +0000 | [diff] [blame] | 154 | mesa-dev@lists.freedesktop.org</a>. |
Emil Velikov | 259e65c | 2016-11-16 00:20:56 +0000 | [diff] [blame] | 155 | When submitting a patch make sure to use |
| 156 | <a href="https://git-scm.com/docs/git-send-email">git send-email</a> |
| 157 | rather than attaching patches to emails. Sending patches as |
| 158 | attachments prevents people from being able to provide in-line review |
| 159 | comments. |
| 160 | </p> |
| 161 | |
| 162 | <p> |
| 163 | When submitting follow-up patches you can use --in-reply-to to make v2, v3, |
| 164 | etc patches show up as replies to the originals. This usually works well |
| 165 | when you're sending out updates to individual patches (as opposed to |
| 166 | re-sending the whole series). Using --in-reply-to makes |
| 167 | it harder for reviewers to accidentally review old patches. |
| 168 | </p> |
| 169 | |
| 170 | <p> |
| 171 | When submitting follow-up patches you should also login to |
| 172 | <a href="https://patchwork.freedesktop.org">patchwork</a> and change the |
| 173 | state of your old patches to Superseded. |
| 174 | </p> |
| 175 | |
| 176 | <h2 id="reviewing">Reviewing Patches</h2> |
| 177 | |
| 178 | <p> |
| 179 | When you've reviewed a patch on the mailing list, please be unambiguous |
| 180 | about your review. That is, state either |
Emil Velikov | b571c07 | 2016-11-16 11:54:54 +0000 | [diff] [blame] | 181 | </p> |
Emil Velikov | 259e65c | 2016-11-16 00:20:56 +0000 | [diff] [blame] | 182 | <pre> |
| 183 | Reviewed-by: Joe Hacker <jhacker@foo.com> |
| 184 | </pre> |
| 185 | or |
| 186 | <pre> |
| 187 | Acked-by: Joe Hacker <jhacker@foo.com> |
| 188 | </pre> |
Emil Velikov | b571c07 | 2016-11-16 11:54:54 +0000 | [diff] [blame] | 189 | <p> |
Emil Velikov | 259e65c | 2016-11-16 00:20:56 +0000 | [diff] [blame] | 190 | Rather than saying just "LGTM" or "Seems OK". |
| 191 | </p> |
| 192 | |
| 193 | <p> |
| 194 | If small changes are suggested, it's OK to say something like: |
Emil Velikov | b571c07 | 2016-11-16 11:54:54 +0000 | [diff] [blame] | 195 | </p> |
Emil Velikov | 259e65c | 2016-11-16 00:20:56 +0000 | [diff] [blame] | 196 | <pre> |
| 197 | With the above fixes, Reviewed-by: Joe Hacker <jhacker@foo.com> |
| 198 | </pre> |
Emil Velikov | b571c07 | 2016-11-16 11:54:54 +0000 | [diff] [blame] | 199 | <p> |
Emil Velikov | 259e65c | 2016-11-16 00:20:56 +0000 | [diff] [blame] | 200 | which tells the patch author that the patch can be committed, as long |
| 201 | as the issues are resolved first. |
| 202 | </p> |
| 203 | |
| 204 | |
| 205 | <h2 id="nominations">Nominating a commit for a stable branch</h2> |
| 206 | |
| 207 | <p> |
Emil Velikov | 0738446 | 2016-11-16 11:51:50 +0000 | [diff] [blame] | 208 | There are three ways to nominate patch for inclusion of the stable branch and |
| 209 | release. |
| 210 | </p> |
| 211 | <ul> |
| 212 | <li> By adding the Cc: mesa-stable@ tag as described below. |
| 213 | <li> Sending the commit ID (as seen in master branch) to the mesa-stable@ mailing list. |
| 214 | <li> Forwarding the patch from the mesa-dev@ mailing list. |
| 215 | </li> |
| 216 | </ul> |
| 217 | <p> |
| 218 | Note: resending patch identical to one on mesa-dev@ or one that differs only |
| 219 | by the extra mesa-stable@ tag is <strong>not</strong> recommended. |
| 220 | </p> |
| 221 | |
| 222 | |
| 223 | <h3 id="thetag">The stable tag</h3> |
| 224 | |
| 225 | <p> |
Emil Velikov | 259e65c | 2016-11-16 00:20:56 +0000 | [diff] [blame] | 226 | If you want a commit to be applied to a stable branch, |
| 227 | you should add an appropriate note to the commit message. |
| 228 | </p> |
| 229 | |
| 230 | <p> |
| 231 | Here are some examples of such a note: |
| 232 | </p> |
| 233 | <ul> |
| 234 | <li>CC: <mesa-stable@lists.freedesktop.org></li> |
| 235 | <li>CC: "9.2 10.0" <mesa-stable@lists.freedesktop.org></li> |
| 236 | <li>CC: "10.0" <mesa-stable@lists.freedesktop.org></li> |
| 237 | </ul> |
| 238 | |
| 239 | Simply adding the CC to the mesa-stable list address is adequate to nominate |
| 240 | the commit for the most-recently-created stable branch. It is only necessary |
| 241 | to specify a specific branch name, (such as "9.2 10.0" or "10.0" in the |
| 242 | examples above), if you want to nominate the commit for an older stable |
| 243 | branch. And, as in these examples, you can nominate the commit for the older |
| 244 | branch in addition to the more recent branch, or nominate the commit |
| 245 | exclusively for the older branch. |
| 246 | |
| 247 | This "CC" syntax for patch nomination will cause patches to automatically be |
| 248 | copied to the mesa-stable@ mailing list when you use "git send-email" to send |
Emil Velikov | 0738446 | 2016-11-16 11:51:50 +0000 | [diff] [blame] | 249 | patches to the mesa-dev@ mailing list. If you prefer using --suppress-cc that |
| 250 | won't have any effect negative effect on the patch nomination. |
Emil Velikov | 259e65c | 2016-11-16 00:20:56 +0000 | [diff] [blame] | 251 | |
Emil Velikov | 0715ba4 | 2016-12-05 16:11:21 +0000 | [diff] [blame] | 252 | <p> |
| 253 | Note: by removing the tag [as the commit is pushed] the patch is |
| 254 | <strong>explicitly</strong> rejected from inclusion in the stable branch(es). |
| 255 | <br> |
| 256 | Thus, drop the line <strong>only</strong> if you want to cancel the nomination. |
| 257 | </p> |
| 258 | |
Emil Velikov | 259e65c | 2016-11-16 00:20:56 +0000 | [diff] [blame] | 259 | <h2 id="criteria">Criteria for accepting patches to the stable branch</h2> |
| 260 | |
| 261 | Mesa has a designated release manager for each stable branch, and the release |
| 262 | manager is the only developer that should be pushing changes to these |
| 263 | branches. Everyone else should simply nominate patches using the mechanism |
| 264 | described above. |
| 265 | |
| 266 | The stable-release manager will work with the list of nominated patches, and |
Andres Gomez | 28158c3 | 2016-11-28 18:47:42 +0200 | [diff] [blame] | 267 | for each patch that meets the criteria below will cherry-pick the patch with: |
Emil Velikov | 259e65c | 2016-11-16 00:20:56 +0000 | [diff] [blame] | 268 | <code>git cherry-pick -x <commit></code>. The <code>-x</code> option is |
Andres Gomez | 28158c3 | 2016-11-28 18:47:42 +0200 | [diff] [blame] | 269 | important so that the picked patch references the commit ID of the original |
Emil Velikov | 259e65c | 2016-11-16 00:20:56 +0000 | [diff] [blame] | 270 | patch. |
| 271 | |
| 272 | The stable-release manager may at times need to force-push changes to the |
| 273 | stable branches, for example, to drop a previously-picked patch that was later |
| 274 | identified as causing a regression). These force-pushes may cause changes to |
| 275 | be lost from the stable branch if developers push things directly. Consider |
| 276 | yourself warned. |
| 277 | |
| 278 | The stable-release manager is also given broad discretion in rejecting patches |
| 279 | that have been nominated for the stable branch. The most basic rule is that |
| 280 | the stable branch is for bug fixes only, (no new features, no |
| 281 | regressions). Here is a non-exhaustive list of some reasons that a patch may |
| 282 | be rejected: |
| 283 | |
| 284 | <ul> |
| 285 | <li>Patch introduces a regression. Any reported build breakage or other |
| 286 | regression caused by a particular patch, (game no longer work, piglit test |
| 287 | changes from PASS to FAIL), is justification for rejecting a patch.</li> |
| 288 | |
| 289 | <li>Patch is too large, (say, larger than 100 lines)</li> |
| 290 | |
| 291 | <li>Patch is not a fix. For example, a commit that moves code around with no |
| 292 | functional change should be rejected.</li> |
| 293 | |
| 294 | <li>Patch fix is not clearly described. For example, a commit message |
| 295 | of only a single line, no description of the bug, no mention of bugzilla, |
| 296 | etc.</li> |
| 297 | |
| 298 | <li>Patch has not obviously been reviewed, For example, the commit message |
| 299 | has no Reviewed-by, Signed-off-by, nor Tested-by tags from anyone but the |
| 300 | author.</li> |
| 301 | |
| 302 | <li>Patch has not already been merged to the master branch. As a rule, bug |
| 303 | fixes should never be applied first to a stable branch. Patches should land |
| 304 | first on the master branch and then be cherry-picked to a stable |
| 305 | branch. (This is to avoid future releases causing regressions if the patch |
| 306 | is not also applied to master.) The only things that might look like |
| 307 | exceptions would be backports of patches from master that happen to look |
| 308 | significantly different.</li> |
| 309 | |
| 310 | <li>Patch depends on too many other patches. Ideally, all stable-branch |
| 311 | patches should be self-contained. It sometimes occurs that a single, logical |
| 312 | bug-fix occurs as two separate patches on master, (such as an original |
| 313 | patch, then a subsequent fix-up to that patch). In such a case, these two |
| 314 | patches should be squashed into a single, self-contained patch for the |
| 315 | stable branch. (Of course, if the squashing makes the patch too large, then |
| 316 | that could be a reason to reject the patch.)</li> |
| 317 | |
| 318 | <li>Patch includes new feature development, not bug fixes. New OpenGL |
| 319 | features, extensions, etc. should be applied to Mesa master and included in |
| 320 | the next major release. Stable releases are intended only for bug fixes. |
| 321 | |
| 322 | Note: As an exception to this rule, the stable-release manager may accept |
| 323 | hardware-enabling "features". For example, backports of new code to support |
| 324 | a newly-developed hardware product can be accepted if they can be reasonably |
| 325 | determined to not have effects on other hardware.</li> |
| 326 | |
| 327 | <li>Patch is a performance optimization. As a rule, performance patches are |
| 328 | not candidates for the stable branch. The only exception might be a case |
| 329 | where an application's performance was recently severely impacted so as to |
| 330 | become unusable. The fix for this performance regression could then be |
| 331 | considered for a stable branch. The optimization must also be |
| 332 | non-controversial and the patches still need to meet the other criteria of |
| 333 | being simple and self-contained</li> |
| 334 | |
| 335 | <li>Patch introduces a new failure mode (such as an assert). While the new |
| 336 | assert might technically be correct, for example to make Mesa more |
| 337 | conformant, this is not the kind of "bug fix" we want in a stable |
| 338 | release. The potential problem here is that an OpenGL program that was |
| 339 | previously working, (even if technically non-compliant with the |
| 340 | specification), could stop working after this patch. So that would be a |
Andres Gomez | 28158c3 | 2016-11-28 18:47:42 +0200 | [diff] [blame] | 341 | regression that is unacceptable for the stable branch.</li> |
Emil Velikov | 259e65c | 2016-11-16 00:20:56 +0000 | [diff] [blame] | 342 | </ul> |
| 343 | |
Timothy Arceri | e260bfe | 2016-11-21 16:30:12 +0000 | [diff] [blame] | 344 | <h2 id="gittips">Git tips</h2> |
| 345 | |
| 346 | <ul> |
Emil Velikov | 6dae5be | 2016-11-28 17:40:04 +0000 | [diff] [blame] | 347 | <li><code>git rebase -i ...</code> is your friend. Don't be afraid to use it. |
| 348 | <li>Apply a fixup to commit FOO. |
| 349 | <pre> |
| 350 | git add ... |
| 351 | git commit --fixup=FOO |
| 352 | git rebase -i --autosquash ... |
| 353 | </pre> |
Timothy Arceri | e260bfe | 2016-11-21 16:30:12 +0000 | [diff] [blame] | 354 | <li>Test for build breakage between patches e.g last 8 commits. |
| 355 | <pre> |
| 356 | git rebase -i --exec="make -j4" HEAD~8 |
| 357 | </pre> |
| 358 | <li>Sets the default mailing address for your repo. |
| 359 | <pre> |
| 360 | git config --local sendemail.to mesa-dev@lists.freedesktop.org |
| 361 | </pre> |
| 362 | <li> Add version to subject line of patch series in this case for the last 8 |
| 363 | commits before sending. |
| 364 | <pre> |
| 365 | git send-email --subject-prefix="PATCH v4" HEAD~8 |
| 366 | git send-email -v4 @~8 # shorter version, inherited from git format-patch |
| 367 | </pre> |
Emil Velikov | a2283b5 | 2016-11-21 17:53:33 +0000 | [diff] [blame] | 368 | <li> Configure git to use the get_reviewer.pl script interactively. Thus you |
| 369 | can avoid adding the world to the CC list. |
| 370 | <pre> |
| 371 | git config sendemail.cccmd "./scripts/get_reviewer.pl -i" |
| 372 | </pre> |
Timothy Arceri | e260bfe | 2016-11-21 16:30:12 +0000 | [diff] [blame] | 373 | </ul> |
| 374 | |
Emil Velikov | 259e65c | 2016-11-16 00:20:56 +0000 | [diff] [blame] | 375 | |
| 376 | </div> |
| 377 | </body> |
| 378 | </html> |