docs/devel/submitting-a-patch.rst

1 .. _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 --------------------
60 -  :ref:`coding-style`
61 -  `Automate a checkpatch run on
62    commit <https://blog.vmsplice.net/2011/03/how-to-automatically-run-checkpatchpl.html>`__
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
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
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
123     git format-patch --stdout -1 > patch;
124     diff -u <(sed -n 's/^-//p' patch) <(sed -n 's/^\+//p' patch)
137 really does need a reindent or other large-scale style fix, submit this
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
174 add an additional line with "Fixes: <at-least-12-digits-of-SHA-commit-id>
176 "Signed-off-by:" line in the commit message.
179 with "Resolves: <URL-of-the-bug>" to the commit message, too. Gitlab can
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
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
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>`__)
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.
261 certain large tree-wide cleanups), or augment it with other interested people.
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
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.
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
348 the `Linux kernel
349 <http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatche…
350 policy.
352 If you wrote the patch, make sure your "From:" and "Signed-off-by:"
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
368 <http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatche…
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
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
428 for stable. In that case, consider adding ``Cc: qemu-stable@nongnu.org``
432 :ref:`stable-process` page.
437 ---------------------------
444     b4 shazam $msg-id
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
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
513 fresh email or series of emails -- don't try to make it a followup to
522 All patches beyond the first version should include a version tag -- for
526 the version applies to the whole series -- even if you only change one
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 ``---``
545 committed. This part should be a self-contained description of what this
548 the ``---`` line and above the patch proper (git format-patch puts the
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
571 those commit messages by hand to include the Reviewed-by tag, so that in
574 that was previously reviewed, remove the reviewed-by tag out of the
585 week or two, by sending an email as a reply-to-all to the patch mail,
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
611 then takes care of :ref:`submitting-a-pull-request`
617 Signed-off-by line in addition to yours, indicating that it went through