docs/devel/submitting-a-patch.rst

7 the documentation. However, we get a lot of patches, and so we have
13 one-shot fix, the bare minimum we ask is that:
22 …- States you are legally able to contribute the code. See :ref:`patch_emails_must_include_a_signed…
24      - The project uses an email list based workflow. See :ref:`submitting_your_patches`
29 preserve CCs and keep non-subscribers in the loop on the threads they
32 volume of email, often over one thousand messages in a week. The list is
37 The larger your contribution is, or if you plan on becoming a long-term
38 contributor, then the more important the rest of this page becomes.
39 Reading the table of contents below should already give you an idea of
40 the basic requirements. Use the table of contents as a reference, and
41 read the parts that you have doubts about.
52 Use the QEMU coding style
72 branches and then only as backports once the code has gone into master.
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
91 points in the commit history where QEMU doesn't work for reasons
92 unrelated to the bug they're chasing.) Put documentation first, not
93 last, so that someone reading the series can do a clean-room evaluation
94 of the documentation, then validate that the code matched the
107 making the refactoring easier to review. Split up the series so that
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'
113 representation that focuses only on the differences across the file
114 rename, instead of showing the entire old file as a deletion and the new
115 file as an insertion. Meanwhile, the 'diff.algorithm' property ensures
117 where all extracted parts occur in the same order both before and after
118 the patch, will reduce churn in trying to treat unrelated ``}`` lines in
119 the original file as separating hunks of changes.
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
136 lines) of the lines you're changing.) If you think a section of code
138 as a separate patch which makes no semantic changes; don't put it in the
142 using the :ref:`trivial-patches` process.
150 historical record of why the changes you applied were necessary or
153 QEMU follows the usual standard for git commit messages: the first line
154 (which becomes the email subject line) is "subsystem: single line
155 summary of change". Whether the "single line summary of change" starts
156 with a capital is a matter of taste, but we prefer that the summary does
159 description of the patch, another blank and your Signed-off-by: line.
161 commit message (so that the text still shows up nicely with "git show"
164 The body of the commit message is a good place to document why your
166 for fixing this bug" (they can go below the ``---`` line in the email so
167 they don't go into the final commit message). Make sure the body of the
168 commit message can be read in isolation even if the reader's mailer
169 displays the subject line some distance apart (that is, a body that
170 starts with "... so that" as a continuation of the subject line is
173 If your patch fixes a commit that is already in the repository, please
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
180 close bugs automatically once commits with the "Resolves:" keyword get
181 merged into the master branch of the project. And if your patch addresses
183 "Buglink: <URL-of-the-bug>" for reference here, too.
201 patches submitted to the list, it still saves everyone time if you
203 is such a large project the default configuration won't create a
204 testing pipeline on GitLab when a branch is pushed. See the :ref:`CI
205 variable documentation<ci_var>` for details on how to control the
208 changes might have an unintended effect on other areas of the code you
214 new feature, or to add a test which exposes the bug that the rest of
215 your series fixes. Keeping separate commits for the test and the fix
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
225 The QEMU project uses a public email based workflow for reviewing and
227 as patches** to the qemu-devel `mailing list
229 contributions should not be posted on the bug tracker, posted on
235 works best for delivering the patch without mangling it, but
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
259 of the affected code. Generally you should accept the suggested CC list, but
270 patches to the QEMU mailing list by following these steps:
277 #. Send your patches to the QEMU mailing list using the web-based
285 CC the relevant maintainer
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
290 that is. Also try using scripts/get_maintainer.pl from the repository
291 for learning the most common committers for the files you touched.
314 Use the right diff format.
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
324 letter, with shallow threading (all patches in the series are
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).
336 If you added binaries to the repository, consider producing the patch
338 git repository to fetch the original commit.
347 this and happy for it to go into QEMU". For full guidance, read the
357 continuous integration), but optional for an isolated patch. The cover
358 letter explains the overall goal of such a series, and also provides a
359 convenient 0/N email for others to reply to the series as a whole. A
361 `git-config <http://git-scm.com/docs/git-config>`__) will generate the
364 When reviewers don't know your goal at the start of their review, they
365 may object to early changes that don't make sense until the end of the
367 their review. A series where the goal is unclear also risks a higher
368 number of review-fix cycles because the reviewers haven't bought into
369 the idea yet. If the cover letter can explain these points to the
370 reviewer, the process will be smoother patches will get merged faster.
371 Make sure your cover letter includes a diffstat of changes made over the
377 Use the RFC tag if needed
387 -  the patch depends on some pending kernel changes which haven't yet
388    been accepted, so the QEMU patch series is blocked until that
390 -  the patch set is not finished yet (perhaps it doesn't cover all use
395 patchset that the submitter themselves is saying shouldn't be applied,
399 -  in the cover letter, be clear about why a patch is an RFC, what areas
400    of the patchset you're looking for review on, and why reviewers
410 to your patch to notify the stable maintainers.
412 For more details on how QEMU's stable process works, refer to the
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
429 of them can be used and b4 will apply the whole series.
434 All patches submitted to the QEMU project go through a code review
442 ideal patch submission. However for the best results you should
458 the issues fixed. This takes a little time and effort on your part, but
462 patches. If someone has spent the time reviewing your code and
464 addressing the comment directly or providing additional justification
465 for the change then it becomes wasted effort. You cannot demand others
466 merge and then fix up your code after the fact.
469 the sender** -- keeping discussion on the mailing list means everybody
470 can follow it. Remember the spirit of the :ref:`code_of_conduct` and
481 from the previous round tends to alienate reviewers and stall your
483 argue that your code was correct in the first place instead of blindly
484 doing everything the reviewer asked. On the other hand, if someone
487 your commit message and/or comments in the code explaining why the code
490 If you fix issues that are raised during review **resend the entire
491 patch series** not just the one patch that was changed. This allows
492 maintainers to easily apply the fixed series without having to manually
493 identify which patches are relevant. Send the new version as a complete
503 All patches beyond the first version should include a version tag -- for
505 they're looking at the most recent version. (The first version of a
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
509 track versions of different patches in the series separately.  `git
512 the ``-v2`` option to make this easier. Send each new revision as a new
523 previous versions, but not in the commit message itself. In an email
524 formatted as a git patch, the commit message is the part above the ``---``
525 line, and this will go into the git changelog when the patch is
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
529 the ``---`` line and above the patch proper (git format-patch puts the
530 diffstat here) is a good place to put remarks for people reading the
531 patch email, and this is where the "changes since previous version"
532 summary belongs. The `git-publish
534 tracking a good summary across versions. Also, the `git-backport-diff
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
553 the next revision, reviewers can spot which patches were already clean
554 from the previous round. Conversely, if you significantly modify a patch
555 that was previously reviewed, remove the reviewed-by tag out of the
556 commit message, as well as listing the changes from the previous
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
573 areas of QEMU patches do just slip through the cracks. If your ping is
574 also ignored, ping again after another week or so. As the submitter, you
575 are the person with the most motivation to get your patch applied, so
585 <http://patchew.org/QEMU/>`__ includes a web interface for tracking the
586 status of various threads that have been posted to the list, and may
589 Once your patch has had enough review on list, the maintainer for that
590 area of code will send notification to the list that they are including
591 your patch in a particular staging branch. Periodically, the maintainer
599 their tree. Occasionally, the maintainer's pull request may hit more
601 resolve the problems. It may take a couple of weeks between when your
607 Return the favor
613 from others as what you submit. Don't worry if you don't know the code
615 review is weak because you are unfamiliar with the code.