docs: split Submitting Patches into separate document

Signed-off-by: Emil Velikov <[email protected]>
Reviewed-by: Brian Paul <[email protected]>

3 files changed, 310 insertions, 285 deletions

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 @@
 <li><a href="helpwanted.html" target="_parent">Help Wanted</a>
 <li><a href="devinfo.html" target="_parent">Development Notes</a>
 <li><a href="codingstyle.html" target="_parent">Coding Style</a>
+<li><a href="submittingpatches.html" target="_parent">Submitting patches</a>
 <li><a href="sourcedocs.html" target="_parent">Source Documentation</a>
 <li><a href="dispatch.html" target="_parent">GL Dispatch</a>
 </ul>
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 @@
 
 
 <ul>
-<li><a href="#submitting">Submitting Patches</a>
 <li><a href="#release">Making a New Mesa Release</a>
 <li><a href="#extensions">Adding Extensions</a>
 </ul>
 
-<h2 id="submitting">Submitting patches</h2>
-
-<p>
-The basic guidelines for submitting patches are:
-</p>
-
-<ul>
-<li>Patches should be sufficiently tested before submitting.
-<li>Code patches should follow Mesa
-<a href="codingstyle.html" target="_parent">coding conventions</a>.
-<li>Whenever possible, patches should only effect individual Mesa/Gallium
-components.
-<li>Patches should never introduce build breaks and should be bisectable (see
-<code>git bisect</code>.)
-<li>Patches should be properly formatted (see below).
-<li>Patches should be submitted to mesa-dev for review using
-<code>git send-email</code>.
-<li>Patches should not mix code changes with code formatting changes (except,
-perhaps, in very trivial cases.)
-</ul>
-
-<h3>Patch formatting</h3>
-
-<p>
-The basic rules for patch formatting are:
-</p>
-
-<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 &lt; 80).
-<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>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>A "Signed-off-by:" line is not required, but not discouraged either.
-<li>If a patch address 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>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>If someone tested your patch, document it with a line like this:
-<pre>
-    Tested-by: Joe Hacker &lt;[email protected]&gt;
-</pre>
-<li>If the patch was reviewed (usually the case) or acked by someone,
-that should be documented with:
-<pre>
-    Reviewed-by: Joe Hacker &lt;[email protected]&gt;
-    Acked-by: Joe Hacker &lt;[email protected]&gt;
-</pre>
-</ul>
-
-
-
-<h3>Testing Patches</h3>
-
-<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>
-Whenever possible and applicable, test the patch with
-<a href="http://piglit.freedesktop.org">Piglit</a> and/or
-<a href="https://android.googlesource.com/platform/external/deqp/">dEQP</a>
-to check for regressions.
-</p>
-
-
-<h3>Mailing Patches</h3>
-
-<p>
-Patches should be sent to the mesa-dev mailing list for review:
-<a href="https://lists.freedesktop.org/mailman/listinfo/mesa-dev">
[email protected]<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>
-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>
-
-<h3>Reviewing Patches</h3>
-
-<p>
-When you've reviewed a patch on the mailing list, please be unambiguous
-about your review.  That is, state either
-<pre>
-    Reviewed-by: Joe Hacker &lt;[email protected]&gt;
-</pre>
-or
-<pre>
-    Acked-by: Joe Hacker &lt;[email protected]&gt;
-</pre>
-Rather than saying just "LGTM" or "Seems OK".
-</p>
-
-<p>
-If small changes are suggested, it's OK to say something like:
-<pre>
-   With the above fixes, Reviewed-by: Joe Hacker &lt;[email protected]&gt;
-</pre>
-which tells the patch author that the patch can be committed, as long
-as the issues are resolved first.
-</p>
-
-
-<h3>Marking a commit as a candidate for a stable branch</h3>
-
-<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: &lt;[email protected]&gt;</li>
-  <li>CC: "9.2 10.0" &lt;[email protected]&gt;</li>
-  <li>CC: "10.0" &lt;[email protected]&gt;</li>
-</ul>
-
-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 [email protected] 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
-<a href="http://cworth.org/~cworth/mesa-stable-queue/">Mesa Stable Queue</a>
-page.
-
-<h3>Criteria for accepting patches to the stable branch</h3>
-
-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:
-<code>git cherry-pick -x &lt;commit&gt;</code>. The <code>-x</code> 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:
-
-<ul>
-  <li>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.</li>
-
-  <li>Patch is too large, (say, larger than 100 lines)</li>
-
-  <li>Patch is not a fix. For example, a commit that moves code around with no
-  functional change should be rejected.</li>
-
-  <li>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.</li>
-
-  <li>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.</li>
-
-  <li>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.</li>
-
-  <li>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.)</li>
-
-  <li>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.</li>
-
-  <li>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</li>
-
-  <li>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.</li>
-</ul>
-
-
 <h2 id="release">Making a New Mesa Release</h2>
 
 <p>
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 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html lang="en">
+<head>
+  <meta http-equiv="content-type" content="text/html; charset=utf-8">
+  <title>Submitting patches</title>
+  <link rel="stylesheet" type="text/css" href="mesa.css">
+</head>
+<body>
+
+<div class="header">
+  <h1>The Mesa 3D Graphics Library</h1>
+</div>
+
+<iframe src="contents.html"></iframe>
+<div class="content">
+
+<h1>Submitting patches</h1>
+
+
+<ul>
+<li><a href="#guidelines">Basic guidelines</a>
+<li><a href="#formatting">Patch formatting</a>
+<li><a href="#testing">Testing Patches</a>
+<li><a href="#mailing">Mailing Patches</a>
+<li><a href="#reviewing">Reviewing Patches</a>
+<li><a href="#nominations">Nominating a commit for a stable branch</a>
+<li><a href="#criteria">Criteria for accepting patches to the stable branch</a>
+</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>Code patches should follow Mesa
+<a href="codingstyle.html" target="_parent">coding conventions</a>.
+<li>Whenever possible, patches should only effect individual Mesa/Gallium
+components.
+<li>Patches should never introduce build breaks and should be bisectable (see
+<code>git bisect</code>.)
+<li>Patches should be properly <a href="#formatting">formatted</a>.
+<li>Patches should be sufficiently <a href="#testing">tested</a> before submitting.
+<li>Patches should be submitted to <a href="#mailing">submitted to mesa-dev</a>
+for <a href="#reviewing">review</a> using <code>git send-email</code>.
+
+</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 &lt; 80).
+<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>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>A "Signed-off-by:" line is not required, but not discouraged either.
+<li>If a patch address 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>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>If someone tested your patch, document it with a line like this:
+<pre>
+    Tested-by: Joe Hacker &lt;[email protected]&gt;
+</pre>
+<li>If the patch was reviewed (usually the case) or acked by someone,
+that should be documented with:
+<pre>
+    Reviewed-by: Joe Hacker &lt;[email protected]&gt;
+    Acked-by: Joe Hacker &lt;[email protected]&gt;
+</pre>
+</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>
+Whenever possible and applicable, test the patch with
+<a href="http://piglit.freedesktop.org">Piglit</a> and/or
+<a href="https://android.googlesource.com/platform/external/deqp/">dEQP</a>
+to check for regressions.
+</p>
+
+
+<h2 id="mailing">Mailing Patches</h2>
+
+<p>
+Patches should be sent to the mesa-dev mailing list for review:
+<a href="https://lists.freedesktop.org/mailman/listinfo/mesa-dev">
[email protected]<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>
+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>
+
+<h2 id="reviewing">Reviewing Patches</h2>
+
+<p>
+When you've reviewed a patch on the mailing list, please be unambiguous
+about your review.  That is, state either
+<pre>
+    Reviewed-by: Joe Hacker &lt;[email protected]&gt;
+</pre>
+or
+<pre>
+    Acked-by: Joe Hacker &lt;[email protected]&gt;
+</pre>
+Rather than saying just "LGTM" or "Seems OK".
+</p>
+
+<p>
+If small changes are suggested, it's OK to say something like:
+<pre>
+   With the above fixes, Reviewed-by: Joe Hacker &lt;[email protected]&gt;
+</pre>
+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>
+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: &lt;[email protected]&gt;</li>
+  <li>CC: "9.2 10.0" &lt;[email protected]&gt;</li>
+  <li>CC: "10.0" &lt;[email protected]&gt;</li>
+</ul>
+
+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 [email protected] 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
+<a href="http://cworth.org/~cworth/mesa-stable-queue/">Mesa Stable Queue</a>
+page.
+
+<h2 id="criteria">Criteria for accepting patches to the stable branch</h2>
+
+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:
+<code>git cherry-pick -x &lt;commit&gt;</code>. The <code>-x</code> 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:
+
+<ul>
+  <li>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.</li>
+
+  <li>Patch is too large, (say, larger than 100 lines)</li>
+
+  <li>Patch is not a fix. For example, a commit that moves code around with no
+  functional change should be rejected.</li>
+
+  <li>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.</li>
+
+  <li>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.</li>
+
+  <li>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.</li>
+
+  <li>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.)</li>
+
+  <li>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.</li>
+
+  <li>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</li>
+
+  <li>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.</li>
+</ul>
+
+
+</div>
+</body>
+</html>