mirror of
https://gitee.com/openharmony/third_party_mesa3d
synced 2024-11-28 18:10:34 +00:00
fae5e1dc74
Fixes: ba28f2136f ("docs: add note about r-b/other tags when resending")
Signed-off-by: Eric Engestrom <eric.engestrom@imgtec.com>
Reviewed-by: Emil Velikov <emil.velikov@collabora.com>
372 lines
14 KiB
HTML
372 lines
14 KiB
HTML
<!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="#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 < 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 <jhacker@foo.com>
|
|
</pre>
|
|
<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>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 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%)
|
|
</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">
|
|
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>
|
|
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>
|
|
<pre>
|
|
Reviewed-by: Joe Hacker <jhacker@foo.com>
|
|
</pre>
|
|
or
|
|
<pre>
|
|
Acked-by: Joe Hacker <jhacker@foo.com>
|
|
</pre>
|
|
<p>
|
|
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 patch for inclusion of the stable branch and
|
|
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>
|
|
</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>
|
|
|
|
|
|
<h3 id="thetag">The stable tag</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: <mesa-stable@lists.freedesktop.org></li>
|
|
<li>CC: "9.2 10.0" <mesa-stable@lists.freedesktop.org></li>
|
|
<li>CC: "10.0" <mesa-stable@lists.freedesktop.org></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. If you prefer using --suppress-cc that
|
|
won't have any effect negative effect on the patch nomination.
|
|
|
|
<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 criteria below will cherry-pick the patch with:
|
|
<code>git cherry-pick -x <commit></code>. The <code>-x</code> option is
|
|
important so that the picked patch references the commit 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 unacceptable for the stable branch.</li>
|
|
</ul>
|
|
|
|
<h2 id="gittips">Git tips</h2>
|
|
|
|
<ul>
|
|
<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 ...
|
|
</pre>
|
|
<li>Test for build breakage between patches e.g last 8 commits.
|
|
<pre>
|
|
git rebase -i --exec="make -j4" HEAD~8
|
|
</pre>
|
|
<li>Sets the default mailing address for your repo.
|
|
<pre>
|
|
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"
|
|
</pre>
|
|
</ul>
|
|
|
|
|
|
</div>
|
|
</body>
|
|
</html>
|