docs/devel/submitting-a-patch.rst

1 .. _submitting-a-patch:
3 Submitting a Patch
13 one-shot fix, the bare minimum we ask is that:
15 .. list-table:: Minimal Checklist for Patches
17    :header-rows: 1
19    * - Check
20      - Reason
21    * - Patches contain Signed-off-by: Your Name <author@email>
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``
24      - The project uses an email list based workflow. See :ref:`submitting_your_patches`
25    * - Be prepared to respond to review comments
26      - Code that doesn't pass review will not get merged. See :ref:`participating_in_code_review`
28 You do not have to subscribe to post (list policy is to reply-to-all to
29 preserve CCs and keep non-subscribers in the loop on the threads they
33 moderated; first-time posts from an email address (whether or not you
37 The larger your contribution is, or if you plan on becoming a long-term
48 --------------------
56 check that you are in compliance with our coding standards. Be aware
60 -  :ref:`coding-style`
61 -  `Automate a checkpatch run on
62    commit <https://blog.vmsplice.net/2011/03/how-to-automatically-run-checkpatchpl.html>`__
69 There's no point submitting a patch which is based on a released version
74 It is also okay to base patches on top of other on-going work that is
77 tag <https://lists.gnu.org/archive/html/qemu-devel/2017-08/msg01288.html>`__
78 line ``Based-on: $MESSAGE_ID`` to your cover letter to make the series
86 Split up longer patches into a patch series of logical code changes.
88 add a file to the makefile in patch one and then add the file itself in
89 patch two. (This rule is here so that people can later use tools like
90 `git bisect <http://git-scm.com/docs/git-bisect>`__ without hitting
93 last, so that someone reading the series can do a clean-room evaluation
108 semantic changes (or even function renames) are done in a separate patch
109 from the raw code motion. Use a one-time setup of ``git config
111 `git-config <http://git-scm.com/docs/git-config>`__). The 'diff.renames'
116 that extracting a non-contiguous subset of one file into a new file, but
118 the patch, will reduce churn in trying to treat unrelated ``}`` lines in
121 Ideally, a code motion patch can be reviewed by doing::
123     git format-patch --stdout -1 > patch;
124     diff -u <(sed -n 's/^-//p' patch) <(sed -n 's/^\+//p' patch)
135 patch. (It's OK to fix coding style issues in the immediate area (few
137 really does need a reindent or other large-scale style fix, submit this
138 as a separate patch which makes no semantic changes; don't put it in the
139 same patch as your bug fix.
142 using the :ref:`trivial-patches` process.
157 not end in a dot. Look at ``git shortlog -30`` for an idea of sample
159 description of the patch, another blank and your Signed-off-by: line.
162 in a 80-columns terminal window).
166 for fixing this bug" (they can go below the ``---`` line in the email so
173 If your patch fixes a commit that is already in the repository, please
174 add an additional line with "Fixes: <at-least-12-digits-of-SHA-commit-id>
175 ("Fixed commit subject")" below the patch description / before your
176 "Signed-off-by:" line in the commit message.
178 If your patch fixes a bug in the gitlab bug tracker, please add a line
179 with "Resolves: <URL-of-the-bug>" to the commit message, too. Gitlab can
181 merged into the master branch of the project. And if your patch addresses
183 "Buglink: <URL-of-the-bug>" for reference here, too.
188  Resolves: https://gitlab.com/qemu-project/qemu/-/issues/42
191 Some other tags that are used in commit messages include "Message-Id:"
192 "Tested-by:", "Acked-by:", "Reported-by:", "Suggested-by:".  See ``git
202 have already tested that your patch compiles and works. Because QEMU
206 running of tests; but it is still wise to also check that your patches
213 your patches - either to ensure that future changes won't regress your
218 bisection doesn't land on a known-broken state.
223 -----------------------
227 as patches** to the qemu-devel `mailing list
228 <https://wiki.qemu.org/Contribute/MailingLists>`__. Patch
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
233 <https://git-send-email.io/>`__ and `hints and tips
234 <https://elixir.bootlin.com/linux/latest/source/Documentation/process/email-clients.rst>`__)
235 works best for delivering the patch without mangling it, but
236 attachments can be used as a last resort on a first-time submission.
240 Use git-publish
243 If you already configured git send-email, you can simply use `git-publish
244 <https://github.com/stefanha/git-publish>`__ to send series.
248     $ git checkout master -b my-feature
249     $ # work on new commits, add your 'Signed-off-by' lines to each
254 Each time you post a series, git-publish will create a local tag with the format
255 ``<branchname>-v<version>`` to record the patch series.
257 When sending patch emails, 'git publish' will consult the output of
261 certain large tree-wide cleanups), or augment it with other interested people.
265 If you cannot send patch emails
268 In rare cases it may not be possible to send properly formatted patch
277 #. Send your patches to the QEMU mailing list using the web-based
278    ``git-send-email`` UI at https://git.sr.ht/~USERNAME/qemu/send-email
281 <https://man.sr.ht/git.sr.ht/#sending-patches-upstream>`__.
295     ~/src/qemu/scripts/get_maintainer.pl -f hw/ide/core.c
297 In fact, you can automate this, via a one-time setup of ``git config
298 sendemail.cccmd 'scripts/get_maintainer.pl --nogit-fallback'`` (Refer to
299 `git-config <http://git-scm.com/docs/git-config>`__.)
311 Use ``git format-patch``
315 `git format-patch <http://git-scm.com/docs/git-format-patch>`__ will
316 produce patch emails in the right format (check the documentation to
318 using ``git send-email`` to mail the files to the mailing list. (We
319 recommend `git send-email <http://git-scm.com/docs/git-send-email>`__
321 messing up whitespace. Some distributions do not include send-email in a
323 such as 'git-email' on Fedora-based systems.) Patch series need a cover
325 in-reply-to the cover letter, but not to each other); single unrelated
327 use ``--numbered`` so the cover and the patch have distinct subject lines).
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
342 Patch emails must include a ``Signed-off-by:`` line
345 Your patches **must** include a Signed-off-by: line. This is a hard
352 If you wrote the patch, make sure your "From:" and "Signed-off-by:"
355 commit just confuses things. If someone else wrote the patch, git will
358 that author's Signed-off-by: line is mandatory, with the same spelling.
360 The name used with "Signed-off-by" does not need to be your legal name,
366 include using ``git commit -s`` or ``git format-patch -s``. For more
376 continuous integration), but optional for an isolated patch. The cover
379 one-time setup of ``git config format.coverletter auto`` (refer to
380 `git-config <http://git-scm.com/docs/git-config>`__) will generate the
387 number of review-fix cycles because the reviewers haven't bought into
399 For example, "[PATCH RFC v2]". ``git format-patch --subject-prefix=RFC``
406 -  the patch depends on some pending kernel changes which haven't yet
407    been accepted, so the QEMU patch series is blocked until that
409 -  the patch set is not finished yet (perhaps it doesn't cover all use
417 -  use it sparingly
418 -  in the cover letter, be clear about why a patch is an RFC, what areas
424 Consider whether your patch is applicable for stable
427 If your patch fixes a severe issue or a regression, it may be applicable
428 for stable. In that case, consider adding ``Cc: qemu-stable@nongnu.org``
429 to your patch to notify the stable maintainers.
432 :ref:`stable-process` page.
437 ---------------------------
444     b4 shazam $msg-id
446 The message id is related to the patch series that has been sent to the mailing
447 list. You need to retrieve the "Message-Id:" header from one of the patches. Any
451 ----------------------------
459 Maintainers are often willing to manually fix up first-time
461 ideal patch submission. However for the best results you should
466 quickly, lesser-loved areas of code may have a longer delay.
473 Not many patches get into QEMU straight away -- it is quite common that
482 suggesting improvements and you simply re-post without either
488 the sender** -- keeping discussion on the mailing list means everybody
501 patch. Reviewers aren't always perfect, so it is okay if you want to
510 patch series** not just the one patch that was changed. This allows
513 fresh email or series of emails -- don't try to make it a followup to
514 version 1. (This helps automatic patch email handling tools distinguish
522 All patches beyond the first version should include a version tag -- for
523 example, "[PATCH v2]". This means people can easily identify whether
525 patch need not say "v1", just [PATCH] is sufficient.) For patch series,
526 the version applies to the whole series -- even if you only change one
527 patch, you resend the entire series and mark it as "v2". Don't try to
529 format-patch <http://git-scm.com/docs/git-format-patch>`__ and `git
530 send-email <http://git-scm.com/docs/git-send-email>`__ both understand
531 the ``-v2`` option to make this easier. Send each new revision as a new
532 top-level thread, rather than burying it in-reply-to an earlier
543 formatted as a git patch, the commit message is the part above the ``---``
544 line, and this will go into the git changelog when the patch is
545 committed. This part should be a self-contained description of what this
546 version of the patch does, written to make sense to anybody who comes
548 the ``---`` line and above the patch proper (git format-patch puts the
550 patch email, and this is where the "changes since previous version"
551 summary belongs. The `git-publish
552 <https://github.com/stefanha/git-publish>`__ script can help with
553 tracking a good summary across versions. Also, the `git-backport-diff
554 <https://github.com/codyprime/git-scripts>`__ script can help focus
560 ---------------
564 Proper use of Reviewed-by: tags can aid review
568 patches with a Reviewed-by tag, stating that they are happy with that
569 patch in isolation (sometimes conditional on minor cleanup, like fixing
571 those commit messages by hand to include the Reviewed-by tag, so that in
573 from the previous round. Conversely, if you significantly modify a patch
574 that was previously reviewed, remove the reviewed-by tag out of the
581 If your patch seems to have been ignored
585 week or two, by sending an email as a reply-to-all to the patch mail,
587 patch on `patchew <https://patchew.org/QEMU/>`__ or
588 `lore.kernel.org <https://lore.kernel.org/qemu-devel/>`__. It's worth
589 double-checking for reasons why your patch might have been ignored
591 review comments on an earlier version?), but often for less-maintained
594 are the person with the most motivation to get your patch applied, so
599 Is my patch in?
602 QEMU has some Continuous Integration machines that try to catch patch
606 send you an automated mail if it detected a problem with your patch.
608 Once your patch has had enough review on list, the maintainer for that
610 your patch in a particular staging branch. Periodically, the maintainer
611 then takes care of :ref:`submitting-a-pull-request`
617 Signed-off-by line in addition to yours, indicating that it went through
621 patch first had a positive review to when it finally lands in qemu.git;
631 patch backlog. A good goal is to try to review at least as many patches