X-Git-Url: https://git.libre-soc.org/?a=blobdiff_plain;f=docs%2Fsubmittingpatches.html;h=ba09aa4ad7329327e7609b27dd4c756bedf86410;hb=33affda8bf6cbcff14d51f6d99635c8f41432cda;hp=77b870a13083d207674a798d3cce67b767b67985;hpb=259e65c03ec495a4a1e0c1d513ae87f7a429c360;p=mesa.git diff --git a/docs/submittingpatches.html b/docs/submittingpatches.html index 77b870a1308..ba09aa4ad73 100644 --- a/docs/submittingpatches.html +++ b/docs/submittingpatches.html @@ -25,6 +25,8 @@
  • Reviewing Patches
  • Nominating a commit for a stable branch
  • Criteria for accepting patches to the stable branch +
  • Sending backports for the stable branch +
  • Git tips

    Basic guidelines

    @@ -40,7 +42,7 @@ components. git bisect.)
  • Patches should be properly formatted.
  • Patches should be sufficiently tested before submitting. -
  • Patches should be submitted to submitted to mesa-dev +
  • Patches should be submitted to mesa-dev for review using git send-email. @@ -71,11 +73,16 @@ if needed. For example: 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 +
  • If a patch addresses a bugzilla issue, that should be noted in the patch comment. For example: 
        Bugzilla: https://bugs.freedesktop.org/show_bug.cgi?id=89689
    +
  • If a patch addresses a issue introduced with earlier commit, that should be +noted in the patch comment. For example: +
    +   Fixes: d7b3707c612 "util/disk_cache: use stat() to check if entry is a directory"
+
  • If there have been several revisions to a patch during the review process, they should be noted such as in this example: 
    @@ -103,6 +110,22 @@ that should be documented with:
     Reviewed-by: Joe Hacker <jhacker@foo.com>
     Acked-by: Joe Hacker <jhacker@foo.com>
    +
  • If sending later revision of a patch, add all the tags - ack, r-b, +Cc: mesa-stable and/or other. This provides reviewers with quick feedback if the +patch has already been reviewed. +
  • In order for your patch to reach the prospective reviewer easier/faster, +use the script scripts/get_reviewer.pl to get a list of individuals and include +them in the CC list. +
    +Please use common sense and do not blindly add everyone. +
    +
    +    $ scripts/get_reviewer.pl --help # to get the help screen
+    $ scripts/get_reviewer.pl -f src/egl/drivers/dri2/platform_android.c
+    Rob Herring  (reviewer:ANDROID EGL SUPPORT,added_lines:188/700=27%,removed_lines:58/283=20%)
+    Tomasz Figa  (reviewer:ANDROID EGL SUPPORT,authored:12/41=29%,added_lines:308/700=44%,removed_lines:115/283=41%)
+    Emil Velikov  (authored:13/41=32%,removed_lines:76/283=27%)
+
    @@ -123,18 +146,30 @@ to update the tests themselves.

    Whenever possible and applicable, test the patch with -Piglit and/or +Piglit and/or dEQP to check for regressions.

    +

    +As mentioned at the begining, patches should be bisectable. +A good way to test this is to make use of the `git rebase` command, +to run your tests on each commit. Assuming your branch is based off +origin/master, you can run: +

    +$ git rebase --interactive --exec "make check" origin/master
+
    +replacing "make check" with whatever other test you want to +run. +

    +

    Mailing Patches

    Patches should be sent to the mesa-dev mailing list for review: -mesa-dev@lists.freedesktop.org. +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 @@ -156,11 +191,22 @@ When submitting follow-up patches you should also login to state of your old patches to Superseded.

    +

    +Some companies' mail server automatically append a legal disclaimer, +usually containing something along the lines of "The information in this +email is confidential" and "distribution is strictly prohibited".
    +These legal notices prevent us from being able to accept your patch, +rendering the whole process pointless. Please make sure these are +disabled before sending your patches. (Note that you may need to contact +your email administrator for this.) +

    +

    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>
    @@ -168,14 +214,17 @@ 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.

    @@ -183,6 +232,28 @@ as the issues are resolved first.

    Nominating a commit for a stable branch

    +

    +There are three ways to nominate a patch for inclusion in the stable branch and +release. +

    + +

    +Note: resending patch identical to one on mesa-dev@ or one that differs only +by the extra mesa-stable@ tag is not recommended. +

    +

    +If you are not the author of the original patch, please Cc: them in your +nomination request. +

    + + +

    The stable tag

    +

    If you want a commit to be applied to a stable branch, you should add an appropriate note to the commit message. @@ -193,43 +264,78 @@ Here are some examples of such a note:

    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. +the commit for all the active stable branches. If the commit is not applicable +for said branch the stable-release manager will reply stating so. 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). +patches to the mesa-dev@ mailing list. If you prefer using --suppress-cc that +won't have any negative effect on the patch nomination. -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. +

    +Note: by removing the tag [as the commit is pushed] the patch is +explicitly rejected from inclusion in the stable branch(es). +
    +Thus, drop the line only if you want to cancel the nomination. +

    + +Alternatively, if one uses the "Fixes" tag as described in the "Patch formatting" +section, it nominates a commit for all active stable branches that include the +commit that is referred to.

    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. +manager is the only developer that should be pushing changes to these branches. +Everyone else should nominate patches using the mechanism described above. + +The following rules define which patches are accepted and which are not. The +stable-release manager is also given broad discretion in rejecting patches +that have been nominated. + + + +If the patch complies with the rules it will be +cherry-picked. Alternatively the release +manager will reply to the patch in question stating why the patch has been +rejected or would request a backport. + +A summary of all the picked/rejected patches will be presented in the +pre-release announcement. 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 @@ -237,70 +343,45 @@ 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: +

    Sending backports for the stable branch

    +By default merge conflicts are resolved by the stable-release manager. In which +case he/she should provide a comment about the changes required, alongside the +Conflicts section. Summary of which will be provided in the +pre-release announcement. +
    +Developers are interested in sending backports are recommended to use either a +[BACKPORT #branch] subject prefix or provides similar information +within the commit summary. + +

    Git tips