Submitting patches
+ + +-
+
- Basic guidelines +
- Patch formatting +
- Testing Patches +
- Mailing Patches +
- Reviewing Patches +
- Nominating a commit for a stable branch +
- Criteria for accepting patches to the stable branch +
Basic guidelines
+ +-
+
- Patches should not mix code changes with code formatting changes (except, +perhaps, in very trivial cases.) +
- Code patches should follow Mesa +coding conventions. +
- Whenever possible, patches should only effect individual Mesa/Gallium +components. +
- Patches should never introduce build breaks and should be bisectable (see
+
git bisect.) + - Patches should be properly formatted. +
- Patches should be sufficiently tested before submitting. +
- Patches should be submitted to submitted to mesa-dev
+for review using
git send-email. + +
Patch formatting
+ +-
+
- Lines should be limited to 75 characters or less so that git logs +displayed in 80-column terminals avoid line wrapping. Note that git +log uses 4 spaces of indentation (4 + 75 < 80). +
- The first line should be a short, concise summary of the change prefixed
+with a module name. Examples:
+
+ mesa: Add support for querying GL_VERTEX_ATTRIB_ARRAY_LONG + + gallium: add PIPE_CAP_DEVICE_RESET_STATUS_QUERY + + i965: Fix missing type in local variable declaration. +
+ - Subsequent patch comments should describe the change in more detail,
+if needed. For example:
+
+ i965: Remove end-of-thread SEND alignment code. + + This was present in Eric's initial implementation of the compaction code + for Sandybridge (commit 077d01b6). There is no documentation saying this + is necessary, and removing it causes no regressions in piglit on any + platform. +
+ - A "Signed-off-by:" line is not required, but not discouraged either. +
- If a patch address a bugzilla issue, that should be noted in the
+patch comment. For example:
+
+ Bugzilla: https://bugs.freedesktop.org/show_bug.cgi?id=89689 +
+ - If there have been several revisions to a patch during the review
+process, they should be noted such as in this example:
+
+ st/mesa: add ARB_texture_stencil8 support (v4) + + if we support stencil texturing, enable texture_stencil8 + there is no requirement to support native S8 for this, + the texture can be converted to x24s8 fine. + + v2: fold fixes from Marek in: + a) put S8 last in the list + b) fix renderable to always test for d/s renderable + fixup the texture case to use a stencil only format + for picking the format for the texture view. + v3: hit fallback for getteximage + v4: put s8 back in front, it shouldn't get picked now (Ilia) +
+ - If someone tested your patch, document it with a line like this:
+
+ Tested-by: Joe Hacker <jhacker@foo.com> +
+ - If the patch was reviewed (usually the case) or acked by someone,
+that should be documented with:
+
+ Reviewed-by: Joe Hacker <jhacker@foo.com> + Acked-by: Joe Hacker <jhacker@foo.com> +
+
Testing Patches
+ ++It should go without saying that patches must be tested. In general, +do whatever testing is prudent. +
+ ++You should always run the Mesa test suite before submitting patches. +The test suite can be run using the 'make check' command. All tests +must pass before patches will be accepted, this may mean you have +to update the tests themselves. +
+ ++Whenever possible and applicable, test the patch with +Piglit and/or +dEQP +to check for regressions. +
+ + +Mailing Patches
+ ++Patches should be sent to the mesa-dev mailing list for review: + +mesa-dev@lists.freedesktop.org. +When submitting a patch make sure to use +git send-email +rather than attaching patches to emails. Sending patches as +attachments prevents people from being able to provide in-line review +comments. +
+ ++When submitting follow-up patches you can use --in-reply-to to make v2, v3, +etc patches show up as replies to the originals. This usually works well +when you're sending out updates to individual patches (as opposed to +re-sending the whole series). Using --in-reply-to makes +it harder for reviewers to accidentally review old patches. +
+ ++When submitting follow-up patches you should also login to +patchwork and change the +state of your old patches to Superseded. +
+ +Reviewing Patches
+ ++When you've reviewed a patch on the mailing list, please be unambiguous +about your review. That is, state either +
+ Reviewed-by: Joe Hacker <jhacker@foo.com> ++or +
+ Acked-by: Joe Hacker <jhacker@foo.com> ++Rather than saying just "LGTM" or "Seems OK". + + +
+If small changes are suggested, it's OK to say something like: +
+ With the above fixes, Reviewed-by: Joe Hacker <jhacker@foo.com> ++which tells the patch author that the patch can be committed, as long +as the issues are resolved first. + + + +
Nominating a commit for a stable branch
+ ++If you want a commit to be applied to a stable branch, +you should add an appropriate note to the commit message. +
+ ++Here are some examples of such a note: +
+-
+
- CC: <mesa-stable@lists.freedesktop.org> +
- CC: "9.2 10.0" <mesa-stable@lists.freedesktop.org> +
- CC: "10.0" <mesa-stable@lists.freedesktop.org> +
Criteria for accepting patches to the stable branch
+ +Mesa has a designated release manager for each stable branch, and the release +manager is the only developer that should be pushing changes to these +branches. Everyone else should simply nominate patches using the mechanism +described above. + +The stable-release manager will work with the list of nominated patches, and +for each patch that meets the crtieria below will cherry-pick the patch with: +git cherry-pick -x <commit>. The -x option is
+important so that the picked patch references the comit ID of the original
+patch.
+
+The stable-release manager may at times need to force-push changes to the
+stable branches, for example, to drop a previously-picked patch that was later
+identified as causing a regression). These force-pushes may cause changes to
+be lost from the stable branch if developers push things directly. Consider
+yourself warned.
+
+The stable-release manager is also given broad discretion in rejecting patches
+that have been nominated for the stable branch. The most basic rule is that
+the stable branch is for bug fixes only, (no new features, no
+regressions). Here is a non-exhaustive list of some reasons that a patch may
+be rejected:
+
+-
+
- Patch introduces a regression. Any reported build breakage or other + regression caused by a particular patch, (game no longer work, piglit test + changes from PASS to FAIL), is justification for rejecting a patch. + +
- Patch is too large, (say, larger than 100 lines) + +
- Patch is not a fix. For example, a commit that moves code around with no + functional change should be rejected. + +
- Patch fix is not clearly described. For example, a commit message + of only a single line, no description of the bug, no mention of bugzilla, + etc. + +
- Patch has not obviously been reviewed, For example, the commit message + has no Reviewed-by, Signed-off-by, nor Tested-by tags from anyone but the + author. + +
- Patch has not already been merged to the master branch. As a rule, bug + fixes should never be applied first to a stable branch. Patches should land + first on the master branch and then be cherry-picked to a stable + branch. (This is to avoid future releases causing regressions if the patch + is not also applied to master.) The only things that might look like + exceptions would be backports of patches from master that happen to look + significantly different. + +
- Patch depends on too many other patches. Ideally, all stable-branch + patches should be self-contained. It sometimes occurs that a single, logical + bug-fix occurs as two separate patches on master, (such as an original + patch, then a subsequent fix-up to that patch). In such a case, these two + patches should be squashed into a single, self-contained patch for the + stable branch. (Of course, if the squashing makes the patch too large, then + that could be a reason to reject the patch.) + +
- Patch includes new feature development, not bug fixes. New OpenGL + features, extensions, etc. should be applied to Mesa master and included in + the next major release. Stable releases are intended only for bug fixes. + + Note: As an exception to this rule, the stable-release manager may accept + hardware-enabling "features". For example, backports of new code to support + a newly-developed hardware product can be accepted if they can be reasonably + determined to not have effects on other hardware. + +
- Patch is a performance optimization. As a rule, performance patches are + not candidates for the stable branch. The only exception might be a case + where an application's performance was recently severely impacted so as to + become unusable. The fix for this performance regression could then be + considered for a stable branch. The optimization must also be + non-controversial and the patches still need to meet the other criteria of + being simple and self-contained + +
- Patch introduces a new failure mode (such as an assert). While the new + assert might technically be correct, for example to make Mesa more + conformant, this is not the kind of "bug fix" we want in a stable + release. The potential problem here is that an OpenGL program that was + previously working, (even if technically non-compliant with the + specification), could stop working after this patch. So that would be a + regression that is unaacceptable for the stable branch. +