docs/devel/submitting-a-patch.rst

6 QEMU welcomes contributions to fix bugs, add functionality or improve
10 likely to be accepted and committed faster.
12 This page seems very long, so if you are only trying to post a quick
22 …- States you are legally able to contribute the code. See :ref:`patch_emails_must_include_a_signed…
23    * - Sent as patch emails to ``qemu-devel@nongnu.org``
25    * - Be prepared to respond to review comments
28 You do not have to subscribe to post (list policy is to reply-to-all to
30 start), although you may find it easier as a subscriber to pick up good
34 subscribed) may be subject to some delay while waiting for a moderator
35 to allow your address.
55 You can run run *scripts/checkpatch.pl <patchfile>* before submitting to
62    commit <https://blog.vmsplice.net/2011/03/how-to-automatically-run-checkpatchpl.html>`__
71 won't even apply to master. We only apply selected bugfixes to release
74 It is also okay to base patches on top of other on-going work that is
75 not yet part of the git master branch. To aid continuous integration
78 line ``Based-on: $MESSAGE_ID`` to your cover letter to make the series
88 add a file to the makefile in patch one and then add the file itself in
92 unrelated to the bug they're chasing.) Put documentation first, not
103 Make code motion patches easy to review
107 making the refactoring easier to review. Split up the series so that
110 diff.renames true;`` ``git config diff.algorithm patience`` (refer to
118 the patch, will reduce churn in trying to treat unrelated ``}`` lines in
126 to focus on the few changes that weren't wholesale code motion.
134 changes to bits of code that would otherwise not be touched by the
135 patch. (It's OK to fix coding style issues in the immediate area (few
164 The body of the commit message is a good place to document why your
171 harder to follow).
179 with "Resolves: <URL-of-the-bug>" to the commit message, too. Gitlab can
200 Although QEMU uses various :ref:`ci` services that attempt to test
201 patches submitted to the list, it still saves everyone time if you
205 variable documentation<ci_var>` for details on how to control the
206 running of tests; but it is still wise to also check that your patches
212 Also, it is a wise idea to include a testsuite addition as part of
213 your patches - either to ensure that future changes won't regress your
214 new feature, or to add a test which exposes the bug that the rest of
216 allows reviewers to rebase the test to occur first to prove it catches
217 the problem, then again to place it last in the series so that
226 merging patches. As a result all contributions to QEMU must be **sent
227 as patches** to the qemu-devel `mailing list
230 forums, or externally hosted and linked to. (We have other mailing
231 lists too, but all patches must go to qemu-devel, possibly with a Cc:
232 to another list.) ``git send-email`` (`step-by-step setup guide
244 <https://github.com/stefanha/git-publish>`__ to send series.
249     $ # work on new commits, add your 'Signed-off-by' lines to each
255 ``<branchname>-v<version>`` to record the patch series.
260 there may sometimes be scenarios where it is appropriate to cut it down (eg on
268 In rare cases it may not be possible to send properly formatted patch
269 emails. You can use `sourcehut <https://sourcehut.org/>`__ to send your
270 patches to the QEMU mailing list by following these steps:
272 #. Register or sign in to your account
277 #. Send your patches to the QEMU mailing list using the web-based
288 Send patches both to the mailing list and CC the maintainer(s) of the
289 files you are modifying. look in the MAINTAINERS file to find out who
298 sendemail.cccmd 'scripts/get_maintainer.pl --nogit-fallback'`` (Refer to
306 Send patches inline so they are easy to reply to with review comments.
316 produce patch emails in the right format (check the documentation to
317 find out how to drive it). You can then edit the cover letter before
318 using ``git send-email`` to mail the files to the mailing list. (We
322 default install of git; you may need to download additional packages,
325 in-reply-to the cover letter, but not to each other); single unrelated
328 Patches are easier to find if they start a new top-level thread, rather
329 than being buried in-reply-to another existing thread.
336 If you added binaries to the repository, consider producing the patch
337 emails using ``git format-patch --no-binary`` and include a link to a
338 git repository to fetch the original commit.
346 requirement because it's how you say "I'm legally okay to contribute
347 this and happy for it to go into QEMU". For full guidance, read the
359 convenient 0/N email for others to reply to the series as a whole. A
360 one-time setup of ``git config format.coverletter auto`` (refer to
365 may object to early changes that don't make sense until the end of the
369 the idea yet. If the cover letter can explain these points to the
384 intend for your patchset to be applied to master, but would like some
394 In general, since it's asking other people to do review work on a
396 it's best to:
410 to your patch to notify the stable maintainers.
412 For more details on how QEMU's stable process works, refer to the
420 If you want to apply an existing series on top of your tree, you can simply use
427 The message id is related to the patch series that has been sent to the mailing
428 list. You need to retrieve the "Message-Id:" header from one of the patches. Any
434 All patches submitted to the QEMU project go through a code review
437 :ref:`maintainers<maintainers>`. You therefore should be prepared to
438 read replies to your messages and be willing to act on them.
440 Maintainers are often willing to manually fix up first-time
443 proactively respond to suggestions with changes or justifications for
451 Stay around to fix problems raised in code review
456 just point out code style issues or commit message typos. You'll need to
457 respond to these, and then send a second version of your patches with
461 Remember that a maintainer is under no obligation to take your
468 When replying to comments on your patches **reply to all and not just
476 Pay attention to review comments
479 Someone took their time to review your work, and it pays to respect that
481 from the previous round tends to alienate reviewers and stall your
482 patch. Reviewers aren't always perfect, so it is okay if you want to
486 turns out to be correct, it's probably a sign that you should improve
492 maintainers to easily apply the fixed series without having to manually
494 fresh email or series of emails -- don't try to make it a followup to
507 the version applies to the whole series -- even if you only change one
508 patch, you resend the entire series and mark it as "v2". Don't try to
512 the ``-v2`` option to make this easier. Send each new revision as a new
513 top-level thread, rather than burying it in-reply-to an earlier
527 version of the patch does, written to make sense to anybody who comes
528 back to look at this commit in git in six months' time. The part below
530 diffstat here) is a good place to put remarks for people reading the
548 When reviewing a large series, a reviewer can reply to some of the
552 those commit messages by hand to include the Reviewed-by tag, so that in
557 version, to make it easier to focus a reviewer's attention to your
562 If your patch seems to have been ignored
566 week or two, by sending an email as a reply-to-all to the patch mail,
567 including the word "ping" and ideally also a link to the page for the
571 (forgot to CC the maintainer? annoyed people by failing to respond to
575 are the person with the most motivation to get your patch applied, so
576 you have to be persistent.
583 QEMU has some Continuous Integration machines that try to catch patch
586 status of various threads that have been posted to the list, and may
590 area of code will send notification to the list that they are including
594 need to send a pull request unless you have contributed enough patches
595 to become a maintainer over a particular section of code. Maintainers
598 Signed-off-by line in addition to yours, indicating that it went through
600 difficult merge conflicts, where you may be requested to help rebase and
602 patch first had a positive review to when it finally lands in qemu.git;
612 patch backlog. A good goal is to try to review at least as many patches
614 base as well as a maintainer; it's perfectly fine to admit when your