From 259e65c03ec495a4a1e0c1d513ae87f7a429c360 Mon Sep 17 00:00:00 2001 From: Emil Velikov Date: Wed, 16 Nov 2016 00:20:56 +0000 Subject: [PATCH] docs: split Submitting Patches into separate document Signed-off-by: Emil Velikov Reviewed-by: Brian Paul --- docs/contents.html | 1 + docs/devinfo.html | 285 --------------------------------- docs/submittingpatches.html | 309 ++++++++++++++++++++++++++++++++++++ 3 files changed, 310 insertions(+), 285 deletions(-) create mode 100644 docs/submittingpatches.html diff --git a/docs/contents.html b/docs/contents.html index cdecac6475b..d2b63a327cb 100644 --- a/docs/contents.html +++ b/docs/contents.html @@ -82,6 +82,7 @@
  • Help Wanted
  • Development Notes
  • Coding Style +
  • Submitting patches
  • Source Documentation
  • GL Dispatch diff --git a/docs/devinfo.html b/docs/devinfo.html index c40ea35c5ca..f5642bc3bc4 100644 --- a/docs/devinfo.html +++ b/docs/devinfo.html @@ -18,295 +18,10 @@ -

    Submitting patches

    - -

    -The basic guidelines for submitting patches are: -

    - -
      -
    • Patches should be sufficiently tested before submitting. -
    • 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 (see below). -
    • Patches should be submitted to mesa-dev for review using -git send-email. -
    • Patches should not mix code changes with code formatting changes (except, -perhaps, in very trivial cases.) -
    - -

    Patch formatting

    - -

    -The basic rules for patch formatting are: -

    - -
      -
    • 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. -

    - - -

    Marking a commit as a candidate 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>
      • -
    - -Simply adding the CC to the mesa-stable list address is adequate to nominate -the commit for the most-recently-created stable branch. It is only necessary -to specify a specific branch name, (such as "9.2 10.0" or "10.0" in the -examples above), if you want to nominate the commit for an older stable -branch. And, as in these examples, you can nominate the commit for the older -branch in addition to the more recent branch, or nominate the commit -exclusively for the older branch. - -This "CC" syntax for patch nomination will cause patches to automatically be -copied to the mesa-stable@ mailing list when you use "git send-email" to send -patches to the mesa-dev@ mailing list. Also, if you realize that a commit -should be nominated for the stable branch after it has already been committed, -you can send a note directly to the mesa-stable@lists.freedesktop.org where -the Mesa stable-branch maintainers will receive it. Be sure to mention the -commit ID of the commit of interest (as it appears in the mesa master branch). - -The latest set of patches that have been nominated, accepted, or rejected for -the upcoming stable release can always be seen on the -Mesa Stable Queue -page. - -

    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.
      • -
    - -

    Making a New Mesa Release

    diff --git a/docs/submittingpatches.html b/docs/submittingpatches.html new file mode 100644 index 00000000000..77b870a1308 --- /dev/null +++ b/docs/submittingpatches.html @@ -0,0 +1,309 @@ + + + + + Submitting patches + + + + +

    +

    The Mesa 3D Graphics Library

    +
    + + +
    + +

    Submitting patches

    + + + + +

    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>
      • +
    + +Simply adding the CC to the mesa-stable list address is adequate to nominate +the commit for the most-recently-created stable branch. It is only necessary +to specify a specific branch name, (such as "9.2 10.0" or "10.0" in the +examples above), if you want to nominate the commit for an older stable +branch. And, as in these examples, you can nominate the commit for the older +branch in addition to the more recent branch, or nominate the commit +exclusively for the older branch. + +This "CC" syntax for patch nomination will cause patches to automatically be +copied to the mesa-stable@ mailing list when you use "git send-email" to send +patches to the mesa-dev@ mailing list. Also, if you realize that a commit +should be nominated for the stable branch after it has already been committed, +you can send a note directly to the mesa-stable@lists.freedesktop.org where +the Mesa stable-branch maintainers will receive it. Be sure to mention the +commit ID of the commit of interest (as it appears in the mesa master branch). + +The latest set of patches that have been nominated, accepted, or rejected for +the upcoming stable release can always be seen on the +Mesa Stable Queue +page. + +

    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.
      • +
    + + +
    + + -- 2.30.2