| <!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"> |
| The Mesa 3D Graphics Library |
| </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="#submit">Submitting 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 affect 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 <a href="#submit">submitted</a> via a merge request for |
| <a href="#reviewing">review</a>. |
| |
| </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 addresses an issue in gitlab, use the Closes: tag |
| For example: |
| <pre> |
| 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" |
| </pre> |
| <li>You can produce those fixes lines by running |
| <pre>git config --global alias.fixes "show -s --pretty='format:Fixes: %h (\"%s\")'"</pre> |
| once and then using <pre>git fixes <sha1></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. |
| </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 'meson test' 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> |
| |
| <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 "meson test -C build/" origin/master |
| </pre> |
| <p> |
| replacing <code>"meson test"</code> with whatever other test you want to |
| run. |
| </p> |
| |
| <h2 id="submit">Submitting Patches</h2> |
| |
| <p> |
| Patches are submitted to the Mesa project via a |
| <a href="https://gitlab.freedesktop.org/mesa/mesa">GitLab</a> Merge Request. |
| </p> |
| |
| <p> |
| Add labels to your MR to help reviewers find it. For example: |
| </p> |
| <ul> |
| <li>Mesa changes affecting all drivers: mesa |
| <li>Hardware vendor specific code: amd, intel, nvidia, ... |
| <li>Driver specific code: anvil, freedreno, i965, iris, radeonsi, |
| radv, vc4, ... |
| <li>Other tag examples: gallium, util |
| </ul> |
| <p> |
| Tick the following when creating the MR. It allows developers to |
| rebase your work on top of master. |
| </p> |
| <pre>Allow commits from members who can merge to the target branch</pre> |
| <p> |
| If you revise your patches based on code review and push an update |
| to your branch, you should maintain a <strong>clean</strong> history |
| in your patches. There should not be "fixup" patches in the history. |
| The series should be buildable and functional after every commit |
| whenever you push the branch. |
| </p> |
| <p> |
| It is your responsibility to keep the MR alive and making progress, |
| as there are no guarantees that a Mesa dev will independently take |
| interest in it. |
| </p> |
| <p> |
| Some other notes: |
| </p> |
| <ul> |
| <li>Make changes and update your branch based on feedback |
| <li>After an update, for the feedback you handled, close the |
| feedback discussion with the "Resolve Discussion" button. This way |
| the reviewers know which feedback got handled and which didn't. |
| <li>Old, stale MR may be closed, but you can reopen it if you |
| still want to pursue the changes |
| <li>You should periodically check to see if your MR needs to be |
| rebased |
| <li>Make sure your MR is closed if your patches get pushed outside |
| of GitLab |
| <li>Please send MRs from a personal fork rather than from the main |
| Mesa repository, as it clutters it unnecessarily. |
| </ul> |
| |
| <h2 id="reviewing">Reviewing Patches</h2> |
| |
| <p> |
| 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, 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> |
| |
| <p> |
| These Reviewed-by, Acked-by, and Tested-by tags should also be amended |
| into commits in a MR before it is merged. |
| </p> |
| |
| <p> |
| 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 <jhacker@example.com>`</pre> |
| <p> |
| This is the markdown format for literal, and will prevent gitlab from hiding |
| the < and > symbols. |
| </p> |
| |
| <p> |
| Review by non-experts is encouraged. Understanding how someone else |
| goes about solving a problem is a great way to learn your way around |
| the project. The submitter is expected to evaluate whether they have |
| an appropriate amount of review feedback from people who also |
| understand the code before merging their patches. |
| </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> 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> |
| <p> |
| If you are not the author of the original patch, please Cc: them in your |
| nomination request. |
| </p> |
| |
| <p> |
| The current patch status can be observed in the <a href="releasing.html#stagingbranch">staging branch</a>. |
| </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> |
| <pre> |
| CC: <mesa-stable@lists.freedesktop.org> |
| </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. |
| </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 |
| 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. |
| |
| <ul> |
| <li>Patch must conform with the <a href="#guidelines">Basic guidelines</a></li> |
| |
| <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> |
| |
| <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> |
| |
| <li>Patch cannot be larger than 100 lines.</li> |
| |
| <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. |
| |
| 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> |
| |
| <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> |
| |
| 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> |
| <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. |
| </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. |
| </p> |
| |
| <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="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 |
| </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> |
| </ul> |
| |
| |
| </div> |
| </body> |
| </html> |