<commit_before><!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>
<li><a href="#backports">Sending backports for the stable branch</a>
<li><a href="#gittips">Git tips</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">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 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>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>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: <NAME> &lt;<EMAIL>&gt;
</pre>
<li>If the patch was reviewed (usually the case) or acked by someone,
that should be documented with:
<pre>
    Reviewed-by: <NAME> &lt;<EMAIL>&gt;
    Acked-by: <NAME> &lt;<EMAIL>&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.
<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
    <NAME> <<EMAIL>> (reviewer:ANDROID EGL SUPPORT,added_lines:188/700=27%,removed_lines:58/283=20%)
    <NAME> <<EMAIL>> (reviewer:ANDROID EGL SUPPORT,authored:12/41=29%,added_lines:308/700=44%,removed_lines:115/283=41%)
    <NAME> <<EMAIL>> (authored:13/41=32%,removed_lines:76/283=27%)
</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="https://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></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
</p><commit_msg>docs/submittingpatches: add mention about legal disclaimers<commit_after><!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>
<li><a href="#backports">Sending backports for the stable branch</a>
<li><a href="#gittips">Git tips</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">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 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>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>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: <NAME> &lt;<EMAIL>&gt;
</pre>
<li>If the patch was reviewed (usually the case) or acked by someone,
that should be documented with:
<pre>
    Reviewed-by: <NAME> &lt;<EMAIL>&gt;
    Acked-by: <NAME> &lt;<EMAIL>&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.
<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
    <NAME> <<EMAIL>> (reviewer:ANDROID EGL SUPPORT,added_lines:188/700=27%,removed_lines:58/283=20%)
    <NAME> <<EMAIL>> (reviewer:ANDROID EGL SUPPORT,authored:12/41=29%,added_lines:308/700=44%,removed_lines:115/283=41%)
    <NAME> <<EMAIL>> (authored:13/41=32%,removed_lines:76/283=27%)
</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="https://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></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>

<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>
When you've reviewed a patch on the mailing list, please be unambiguous
about your review.  That is, state either
</p>
{'fraction_non_alphanumeric': 0.111785890826919, 'fraction_numerical': 0.017230421580396865, 'mean_word_length': 4.56026698076168, 'pattern_counts': {'":': 0, '<': 312, '<?xml version=': 0, '>': 312, 'https://': 12, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7457624', 'n_tokens_mistral': 4694, 'n_tokens_neox': 4423, 'n_words': 1751}