Merge Mesa 20.1.6

1 files changed, 85 insertions, 156 deletions

diff --git a/lib/mesa/docs/submittingpatches.html b/lib/mesa/docs/submittingpatches.html
index 786af1045..fb614a790 100644
--- a/lib/mesa/docs/submittingpatches.html
+++ b/lib/mesa/docs/submittingpatches.html
@@ -42,10 +42,8 @@ components.
 <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 <a href="#submit">submitted</a>
-to <a href="#mailing">mesa-dev</a> or with
-a <a href="#merge-request">merge request</a>
-for <a href="#reviewing">review</a>.
+<li>Patches should be <a href="#submit">submitted</a> via a merge request for
+<a href="#reviewing">review</a>.
 
 </ul>
 
@@ -58,32 +56,36 @@ 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
+mesa: Add support for querying GL_VERTEX_ATTRIB_ARRAY_LONG
 
-    gallium: add PIPE_CAP_DEVICE_RESET_STATUS_QUERY
+gallium: add PIPE_CAP_DEVICE_RESET_STATUS_QUERY
 
-    i965: Fix missing type in local variable declaration.
+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.
+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.
+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 addresses a bugzilla issue, that should be noted in the
-patch comment.  For example:
+<li>If a patch addresses an issue in gitlab, use the Closes: tag
+For example:
 <pre>
-   Bugzilla: https://bugs.freedesktop.org/show_bug.cgi?id=89689
+Closes: https://gitlab.freedesktop.org/mesa/mesa/-/issues/1
 </pre>
+<p>Prefer the full url to just <code>Closes: #1</code>, since the url makes it
+easier to get to the bug page from <code>git log</code></p>
+<b>Do not use the Fixes: tag for this!</b> Mesa already uses Fixes for something else.
+
 <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"
+Fixes: d7b3707c612 "util/disk_cache: use stat() to check if entry is a directory"
 </pre>
 <li>You can produce those fixes lines by running
 <pre>git config --global alias.fixes "show -s --pretty='format:Fixes: %h (\"%s\")'"</pre>
@@ -91,46 +93,33 @@ once and then using <pre>git fixes &lt;sha1&gt;</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)
+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;jhacker@foo.com&gt;
+Tested-by: Joe Hacker &lt;jhacker@foo.com&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;jhacker@foo.com&gt;
-    Acked-by: Joe Hacker &lt;jhacker@foo.com&gt;
+Reviewed-by: Joe Hacker &lt;jhacker@foo.com&gt;
+Acked-by: Joe Hacker &lt;jhacker@foo.com&gt;
 </pre>
 <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>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.
-<p>
-Please use common sense and do <strong>not</strong> blindly add everyone.
-</p>
-<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 &lt;robh@kernel.org&gt; (reviewer:ANDROID EGL SUPPORT,added_lines:188/700=27%,removed_lines:58/283=20%)
-    Tomasz Figa &lt;tfiga@chromium.org&gt; (reviewer:ANDROID EGL SUPPORT,authored:12/41=29%,added_lines:308/700=44%,removed_lines:115/283=41%)
-    Emil Velikov &lt;emil.l.velikov@gmail.com&gt; (authored:13/41=32%,removed_lines:76/283=27%)
-</pre>
 </ul>
 
 
@@ -157,7 +146,7 @@ to check for regressions.
 </p>
 
 <p>
-As mentioned at the begining, patches should be bisectable.
+As mentioned at the beginning, 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:
@@ -170,68 +159,14 @@ replacing <code>"meson test"</code> with whatever other test you want to
 run.
 </p>
 
-
 <h2 id="submit">Submitting Patches</h2>
 
 <p>
-Patches may be submitted to the Mesa project by
-<a href="#mailing">email</a> or with a
-GitLab <a href="#merge-request">merge request</a>. To prevent
-duplicate code review, only use one method to submit your changes.
-</p>
-
-<h3 id="mailing">Mailing Patches</h3>
-
-<p>
-Patches may 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.
+Patches are submitted to the Mesa project via a
+<a href="https://gitlab.freedesktop.org/mesa/mesa">GitLab</a> Merge Request.
 </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>
-
-<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".
-</p>
-<p>
-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>
-
-<h3 id="merge-request">GitLab Merge Requests</h3>
-
-<p>
-  <a href="https://gitlab.freedesktop.org/mesa/mesa">GitLab</a> Merge
-  Requests (MR) can also be used to submit patches for Mesa.
-</p>
-
-<p>
-  If the MR may have interest for most of the Mesa community, you can
-  send an email to the mesa-dev email list including a link to the MR.
-  Don't send the patch to mesa-dev, just the MR link.
-</p>
-<p>
   Add labels to your MR to help reviewers find it. For example:
 </p>
 <ul>
@@ -279,23 +214,22 @@ your email administrator for this.)
 <h2 id="reviewing">Reviewing Patches</h2>
 
 <p>
-  To participate in code review, you should monitor the
-  <a href="https://lists.freedesktop.org/mailman/listinfo/mesa-dev">
-  mesa-dev</a> email list and the GitLab
-  Mesa <a href="https://gitlab.freedesktop.org/mesa/mesa/merge_requests">Merge
-  Requests</a> page.
+  To participate in code review, you can monitor the GitLab Mesa
+ <a href="https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests">Merge
+  Requests</a> page, and/or register for notifications in your gitlab
+  settings.
 </p>
 
 <p>
-When you've reviewed a patch on the mailing list, please be unambiguous
-about your review.  That is, state either
+When you've reviewed a patch, please be unambiguous about your review.
+  That is, state either
 </p>
 <pre>
-    Reviewed-by: Joe Hacker &lt;jhacker@foo.com&gt;
+Reviewed-by: Joe Hacker &lt;jhacker@foo.com&gt;
 </pre>
 or
 <pre>
-    Acked-by: Joe Hacker &lt;jhacker@foo.com&gt;
+Acked-by: Joe Hacker &lt;jhacker@foo.com&gt;
 </pre>
 <p>
 Rather than saying just "LGTM" or "Seems OK".
@@ -305,7 +239,7 @@ Rather than saying just "LGTM" or "Seems OK".
 If small changes are suggested, it's OK to say something like:
 </p>
 <pre>
-   With the above fixes, Reviewed-by: Joe Hacker &lt;jhacker@foo.com&gt;
+With the above fixes, Reviewed-by: Joe Hacker &lt;jhacker@foo.com&gt;
 </pre>
 <p>
 which tells the patch author that the patch can be committed, as long
@@ -322,7 +256,7 @@ When providing a Reviewed-by, Acked-by, or Tested-by tag in a gitlab MR,
 enclose the tag in backticks:
 </p>
 <pre>
-  `Reviewed-by: Joe Hacker &lt;jhacker@example.com&gt;`</pre>
+`Reviewed-by: Joe Hacker &lt;jhacker@example.com&gt;`</pre>
 <p>
 This is the markdown format for literal, and will prevent gitlab from hiding
 the &lt; and &gt; symbols.
@@ -344,13 +278,14 @@ release.
 </p>
 <ul>
 <li> By adding the Cc: mesa-stable@ tag as described below.
-<li> Sending the commit ID (as seen in master branch) to the mesa-stable@ mailing list.
-<li> Forwarding the patch from the mesa-dev@ mailing list.
+<li> By adding the fixes: tag as described below.
+<li> By submitting a merge request against the "staging/year.quarter" branch on gitlab.
 </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.
+Please <strong>DO NOT</strong> send patches to
+mesa-stable@lists.freedesktop.org, it is not monitored actively and is a
+historical artifact.
 </p>
 <p>
 If you are not the author of the original patch, please Cc: them in your
@@ -369,31 +304,27 @@ you should add an appropriate note to the commit message.
 </p>
 
 <p>
+Using a "fixes tag" as described in <a href="#formatting">Patch formatting</a>
+is the preferred way to nominate a commit that you know ahead of time should be
+backported. There are scripts that will figure out which releases to apply the
+patch to automatically, so you don't need to figure it out.
+</p>
+
+<p>
+Alternatively, you may use a "CC:" tag.
+
 Here are some examples of such a note:
 </p>
 <pre>
-CC: &lt;mesa-stable@lists.freedesktop.org&gt;
+CC: 20.0 19.3 &lt;mesa-stable@lists.freedesktop.org&gt;
 </pre>
 
-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.
-
 <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).
-Thus, drop the line <strong>only</strong> if you want to cancel the nomination.
+Using the CC tag <strong>should</strong> include the stable branches you want
+to nominate the patch to. If you do not provide any version it is nominated to
+all active stable branches.
 </p>
 
-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.
-
 <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
@@ -442,9 +373,6 @@ If the patch complies with the rules it will be
 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
@@ -453,16 +381,22 @@ yourself warned.
 
 <h2 id="backports">Sending backports for the stable branch</h2>
 <p>
-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.
+By default merge conflicts are resolved by the stable-release manager. The
+release maintainer should resolve trivial conflicts, but for complex conflicts
+they should ask the original author to provide a backport or de-nominate the
+patch.
 </p>
 
 <p>
-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.
+For patches that either need to be nominated after they've landed in master, or
+that are known ahead of time to not not apply cleanly to a stable branch (such
+as due to a rename), using a gitlab MR is most appropriate.
+
+The MR should be based on and target the staging/year.quarter branch, not on
+the year.quarter branch, per the stable branch policy.
+
+Assigning the MR to release maintainer for said branch or mentioning them is
+helpful, but not required.
 </p>
 
 <h2 id="gittips">Git tips</h2>
@@ -471,28 +405,23 @@ within the commit summary.
 <li><code>git rebase -i ...</code> is your friend. Don't be afraid to use it.
 <li>Apply a fixup to commit FOO.
 <pre>
-    git add ...
-    git commit --fixup=FOO
-    git rebase -i --autosquash ...
+git add ...
+git commit --fixup=FOO
+git rebase -i --autosquash ...
 </pre>
 <li>Test for build breakage between patches e.g last 8 commits.
 <pre>
-    git rebase -i --exec="ninja -C build/" HEAD~8
+git rebase -i --exec="ninja -C build/" HEAD~8
 </pre>
 <li>Sets the default mailing address for your repo.
 <pre>
-    git config --local sendemail.to mesa-dev@lists.freedesktop.org
+git config --local sendemail.to mesa-dev@lists.freedesktop.org
 </pre>
 <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> 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"
+git send-email --subject-prefix="PATCH v4" HEAD~8
+git send-email -v4 @~8 # shorter version, inherited from git format-patch
 </pre>
 </ul>