diff options
Diffstat (limited to 'docs/submittingpatches.rst')
| -rw-r--r-- | docs/submittingpatches.rst | 651 |
1 files changed, 312 insertions, 339 deletions
diff --git a/docs/submittingpatches.rst b/docs/submittingpatches.rst index f551b03f57..186ee7e494 100644 --- a/docs/submittingpatches.rst +++ b/docs/submittingpatches.rst @@ -1,371 +1,344 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -<html lang="en"><head> - <meta content="text/html; charset=utf-8" http-equiv="content-type"/> - <title>Submitting patches</title> - <link href="mesa.css" rel="stylesheet" type="text/css"/> -</head> -<body> - - - - - - -<h1>Submitting patches</h1> - - -<ul> -<li><a href="#guidelines">Basic guidelines</a> -</li><li><a href="#formatting">Patch formatting</a> -</li><li><a href="#testing">Testing Patches</a> -</li><li><a href="#mailing">Mailing Patches</a> -</li><li><a href="#reviewing">Reviewing Patches</a> -</li><li><a href="#nominations">Nominating a commit for a stable branch</a> -</li><li><a href="#criteria">Criteria for accepting patches to the stable branch</a> -</li><li><a href="#backports">Sending backports for the stable branch</a> -</li><li><a href="#gittips">Git tips</a> -</li></ul> - -<h2 id="guidelines">Basic guidelines</h2> - -<ul> -<li>Patches should not mix code changes with code formatting changes (except, -perhaps, in very trivial cases.) -</li><li>Code patches should follow Mesa -<a href="codingstyle.html" target="_parent">coding conventions</a>. -</li><li>Whenever possible, patches should only effect individual Mesa/Gallium -components. -</li><li>Patches should never introduce build breaks and should be bisectable (see -<code>git bisect</code>.) -</li><li>Patches should be properly <a href="#formatting">formatted</a>. -</li><li>Patches should be sufficiently <a href="#testing">tested</a> before submitting. -</li><li>Patches should be submitted to <a href="#mailing">mesa-dev</a> -for <a href="#reviewing">review</a> using <code>git send-email</code>. - -</li></ul> - -<h2 id="formatting">Patch formatting</h2> - -<ul> -<li>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). -</li><li>The first line should be a short, concise summary of the change prefixed -with a module name. Examples: -<pre> 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. -</pre> -</li><li>Subsequent patch comments should describe the change in more detail, -if needed. For example: -<pre> 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. -</pre> -</li><li>A "Signed-off-by:" line is not required, but not discouraged either. -</li><li>If a patch addresses a bugzilla issue, that should be noted in the -patch comment. For example: -<pre> Bugzilla: https://bugs.freedesktop.org/show_bug.cgi?id=89689 -</pre> -</li><li>If a patch addresses a issue introduced with earlier commit, that should be -noted in the patch comment. For example: -<pre> Fixes: d7b3707c612 "util/disk_cache: use stat() to check if entry is a directory" -</pre> -</li><li>If there have been several revisions to a patch during the review -process, they should be noted such as in this example: -<pre> 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) -</pre> -</li><li>If someone tested your patch, document it with a line like this: -<pre> Tested-by: Joe Hacker <jhacker@foo.com> -</pre> -</li><li>If the patch was reviewed (usually the case) or acked by someone, -that should be documented with: -<pre> Reviewed-by: Joe Hacker <jhacker@foo.com> - Acked-by: Joe Hacker <jhacker@foo.com> -</pre> -</li><li>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. -</li><li>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. -<br/> -Please use common sense and do <strong>not</strong> blindly add everyone. -<br/> -<pre> $ scripts/get_reviewer.pl --help # to get the help screen - $ scripts/get_reviewer.pl -f src/egl/drivers/dri2/platform_android.c - Rob Herring <robh@kernel.org> (reviewer:ANDROID EGL SUPPORT,added_lines:188/700=27%,removed_lines:58/283=20%) - Tomasz Figa <tfiga@chromium.org> (reviewer:ANDROID EGL SUPPORT,authored:12/41=29%,added_lines:308/700=44%,removed_lines:115/283=41%) - Emil Velikov <emil.l.velikov@gmail.com> (authored:13/41=32%,removed_lines:76/283=27%) -</emil.l.velikov@gmail.com></tfiga@chromium.org></robh@kernel.org></pre> -</li></ul> - - - -<h2 id="testing">Testing Patches</h2> - -<p> -It should go without saying that patches must be tested. In general, -do whatever testing is prudent. -</p> - -<p> -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. -</p> - -<p> +Submitting patches +================== + +- `Basic guidelines <#guidelines>`__ +- `Patch formatting <#formatting>`__ +- `Testing Patches <#testing>`__ +- `Mailing Patches <#mailing>`__ +- `Reviewing Patches <#reviewing>`__ +- `Nominating a commit for a stable branch <#nominations>`__ +- `Criteria for accepting patches to the stable branch <#criteria>`__ +- `Sending backports for the stable branch <#backports>`__ +- `Git tips <#gittips>`__ + +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 <codingstyle.html>`__. +- 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 <#formatting>`__. +- Patches should be sufficiently `tested <#testing>`__ before + submitting. +- Patches should be submitted to `mesa-dev <#mailing>`__ for + `review <#reviewing>`__ 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 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: + + :: + + 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> + +- 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%) + +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 -<a href="https://piglit.freedesktop.org">Piglit</a> and/or -<a href="https://android.googlesource.com/platform/external/deqp/">dEQP</a> -to check for regressions. -</p> - -<p> -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 -<code>origin/master</code>, you can run: -</p><pre>$ git rebase --interactive --exec "make check" origin/master -</pre> -replacing <code>"make check"</code> with whatever other test you want to -run. -<p></p> - - -<h2 id="mailing">Mailing Patches</h2> - -<p> +`Piglit <https://piglit.freedesktop.org>`__ and/or +`dEQP <https://android.googlesource.com/platform/external/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: -<a href="https://lists.freedesktop.org/mailman/listinfo/mesa-dev"> -mesa-dev@lists.freedesktop.org</a>. -When submitting a patch make sure to use -<a href="https://git-scm.com/docs/git-send-email">git send-email</a> -rather than attaching patches to emails. Sending patches as -attachments prevents people from being able to provide in-line review -comments. -</p> - -<p> -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. -</p> - -<p> +`mesa-dev@lists.freedesktop.org <https://lists.freedesktop.org/mailman/listinfo/mesa-dev>`__. +When submitting a patch make sure to use `git +send-email <https://git-scm.com/docs/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 -<a href="https://patchwork.freedesktop.org">patchwork</a> and change the -state of your old patches to Superseded. -</p> - -<p> -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".<br/> -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.) -</p> - -<h2 id="reviewing">Reviewing Patches</h2> - -<p> +`patchwork <https://patchwork.freedesktop.org>`__ and change the 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 -</p> -<pre> Reviewed-by: Joe Hacker <jhacker@foo.com> -</pre> +about your review. That is, state either + +:: + + Reviewed-by: Joe Hacker <jhacker@foo.com> + or -<pre> Acked-by: Joe Hacker <jhacker@foo.com> -</pre> -<p> + +:: + + Acked-by: Joe Hacker <jhacker@foo.com> + Rather than saying just "LGTM" or "Seems OK". -</p> -<p> If small changes are suggested, it's OK to say something like: -</p> -<pre> With the above fixes, Reviewed-by: Joe Hacker <jhacker@foo.com> -</pre> -<p> -which tells the patch author that the patch can be committed, as long -as the issues are resolved first. -</p> - - -<h2 id="nominations">Nominating a commit for a stable branch</h2> - -<p> -There are three ways to nominate a patch for inclusion in the stable branch and -release. -</p> -<ul> -<li> By adding the Cc: mesa-stable@ tag as described below. -</li><li> Sending the commit ID (as seen in master branch) to the mesa-stable@ mailing list. -</li><li> Forwarding the patch from the mesa-dev@ mailing list. -</li> -</ul> -<p> -Note: resending patch identical to one on mesa-dev@ or one that differs only -by the extra mesa-stable@ tag is <strong>not</strong> recommended. -</p> -<p> + +:: + + 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 +--------------------------------------- + +There are three ways to nominate a patch for inclusion in the stable +branch and release. + +- By adding the Cc: mesa-stable@ tag as described below. +- Sending the commit ID (as seen in master branch) to the mesa-stable@ + mailing list. +- Forwarding the patch from the mesa-dev@ mailing list. + +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. -</p> +The stable tag +~~~~~~~~~~~~~~ -<h3 id="thetag">The stable tag</h3> +If you want a commit to be applied to a stable branch, you should add an +appropriate note to the commit message. -<p> -If you want a commit to be applied to a stable branch, -you should add an appropriate note to the commit message. -</p> - -<p> Here are some examples of such a note: -</p> -<ul> - <li>CC: <mesa-stable@lists.freedesktop.org></li> -</ul> -Simply adding the CC to the mesa-stable list address is adequate to nominate -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. +- CC: <mesa-stable@lists.freedesktop.org> + +Simply adding the CC to the mesa-stable list address is adequate to +nominate 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. If you +prefer using --suppress-cc that won't have any negative effect on the +patch nomination. + +| 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 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. + +- Patch must conform with the `Basic guidelines <#guidelines>`__ +- Patch must have landed in master first. In case where the original + patch is too large and/or otherwise contradicts with the rules set + within, a backport is appropriate. +- It must not introduce a regression - be that build or runtime wise. + Note: If the regression is due to faulty piglit/dEQP/CTS/other test + the latter must be fixed first. A reference to the offending test(s) + and respective fix(es) should be provided in the nominated patch. +- Patch cannot be larger than 100 lines. +- Patches that move code around with no functional change should be + rejected. +- Patch must be a bug fix and not a new feature. Note: An exception to + this rule, are hardware-enabling "features". For example, + `backports <#backports>`__ of new code to support a newly-developed + hardware product can be accepted if they can be reasonably determined + not to have effects on other hardware. +- Patch must be reviewed, For example, the commit message has + Reviewed-by, Signed-off-by, or Tested-by tags from someone but the + author. +- Performance patches are considered only if they provide information + about the hardware, program in question and observed improvement. Use + numbers to represent your measurements. -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. If you prefer using --suppress-cc that -won't have any negative effect on the patch nomination. +If the patch complies with the rules it will be +`cherry-picked <releasing.html#pickntest>`__. 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 <releasing.html#prerelease>`__ 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 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. -<p> -Note: by removing the tag [as the commit is pushed] the patch is -<strong>explicitly</strong> rejected from inclusion in the stable branch(es). -<br/> -Thus, drop the line <strong>only</strong> if you want to cancel the nomination. -</p> +Sending backports for the stable branch +--------------------------------------- -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. +| 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 <releasing.html#prerelease>`__ + 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. -<h2 id="criteria">Criteria for accepting patches to the stable branch</h2> +Git tips +-------- -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 nominate patches using the mechanism described above. +- ``git rebase -i ...`` is your friend. Don't be afraid to use it. +- Apply a fixup to commit FOO. -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. + :: -<ul> - <li>Patch must conform with the <a href="#guidelines">Basic guidelines</a></li> + git add ... + git commit --fixup=FOO + git rebase -i --autosquash ... - <li>Patch must have landed in master first. In case where the original - patch is too large and/or otherwise contradicts with the rules set within, a - backport is appropriate.</li> +- Test for build breakage between patches e.g last 8 commits. - <li>It must not introduce a regression - be that build or runtime wise. + :: - Note: If the regression is due to faulty piglit/dEQP/CTS/other test the - latter must be fixed first. A reference to the offending test(s) and - respective fix(es) should be provided in the nominated patch.</li> + git rebase -i --exec="make -j4" HEAD~8 - <li>Patch cannot be larger than 100 lines.</li> +- Sets the default mailing address for your repo. - <li>Patches that move code around with no functional change should be - rejected.</li> + :: - <li>Patch must be a bug fix and not a new feature. + git config --local sendemail.to mesa-dev@lists.freedesktop.org - Note: An exception to this rule, are hardware-enabling "features". For - example, <a href="#backports">backports</a> of new code to support a - newly-developed hardware product can be accepted if they can be reasonably - determined not to have effects on other hardware.</li> +- Add version to subject line of patch series in this case for the last + 8 commits before sending. - <li>Patch must be reviewed, For example, the commit message has Reviewed-by, - Signed-off-by, or Tested-by tags from someone but the author.</li> + :: - <li>Performance patches are considered only if they provide information - about the hardware, program in question and observed improvement. Use numbers - to represent your measurements.</li> -</ul> + git send-email --subject-prefix="PATCH v4" HEAD~8 + git send-email -v4 @~8 # shorter version, inherited from git format-patch -If the patch complies with the rules it will be -<a href="releasing.html#pickntest">cherry-picked</a>. 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 -<a href="releasing.html#prerelease">pre-release</a> 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 -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. - -<h2 id="backports">Sending backports for the stable branch</h2> -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 -<code>Conflicts</code> section. Summary of which will be provided in the -<a href="releasing.html#prerelease">pre-release</a> announcement. -<br/> -Developers are interested in sending backports are recommended to use either a -<code>[BACKPORT #branch]</code> subject prefix or provides similar information -within the commit summary. - -<h2 id="gittips">Git tips</h2> - -<ul> -<li><code>git rebase -i ...</code> is your friend. Don't be afraid to use it. -</li><li>Apply a fixup to commit FOO. -<pre> git add ... - git commit --fixup=FOO - git rebase -i --autosquash ... -</pre> -</li><li>Test for build breakage between patches e.g last 8 commits. -<pre> git rebase -i --exec="make -j4" HEAD~8 -</pre> -</li><li>Sets the default mailing address for your repo. -<pre> git config --local sendemail.to mesa-dev@lists.freedesktop.org -</pre> -</li><li> Add version to subject line of patch series in this case for the last 8 -commits before sending. -<pre> git send-email --subject-prefix="PATCH v4" HEAD~8 - git send-email -v4 @~8 # shorter version, inherited from git format-patch -</pre> -</li><li> Configure git to use the get_reviewer.pl script interactively. Thus you -can avoid adding the world to the CC list. -<pre> git config sendemail.cccmd "./scripts/get_reviewer.pl -i" -</pre> -</li></ul> - - - - - -</body></html> +- Configure git to use the get\_reviewer.pl script interactively. Thus + you can avoid adding the world to the CC list. + + :: + + git config sendemail.cccmd "./scripts/get_reviewer.pl -i" |