|
|
| (67 intermediate revisions by 13 users not shown) |
| Line 1: |
Line 1: |
| QEMU welcomes contributions of code (either fixing bugs or adding new functionality). However, we get a lot of patches, and so we have some guidelines about submitting patches. If you follow these, you'll help make our task of code review easier and your patch is likely to be committed faster.
| | Moved at https://www.qemu.org/docs/master/devel/submitting-a-patch.html |
| | |
| | |
| All contributions to QEMU must be '''sent as patches''' to the qemu-devel [[MailingLists|mailing list]]. Patch contributions should not be posted on the bug tracker, posted on forums, or externally hosted and linked to.
| |
| | |
| Send patches to the mailing list and '''CC the relevant maintainer''' -- look in the MAINTAINERS file to find out who that is.
| |
| | |
| '''Send patches inline''' so they are easy to reply to with review comments. Do not put patches in attachments.
| |
| | |
| '''Patch emails must include a Signed-off-by: line'''. For more information see [http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob;f=Documentation/SubmittingPatches;h=689e2371095cc5dfea9927120009341f369159aa;hb=f6f94e2ab1b33f0082ac22d71f66385a60d8157f#l297 SubmittingPatches 1.12]. This is vital or we will not be able to apply your patch! Please use your real name to sign a patch (not an alias name).
| |
| | |
| '''Follow the coding style''' and run ''scripts/checkpatch.pl <patchfile>'' before submitting. (Be aware that checkpatch.pl is not infallible, though, especially where C preprocessor macros are involved; use some common sense too.) See also:
| |
| * [http://git.qemu.org/?p=qemu.git;a=blob;f=CODING_STYLE;hb=HEAD QEMU Coding Style]
| |
| * [http://git.qemu.org/?p=qemu.git;a=blob;f=HACKING;hb=HEAD QEMU Coding Guidelines]
| |
| | |
| '''Correct English''' is appreciated. If you are not sure, [[Contribute/SpellCheck|codespell]] or other programs help finding the most common spelling mistakes in code and documentation.
| |
| | |
| '''Patches should be against current git master'''. There's no point submitting a patch which is based on a released version of QEMU because development will have moved on from then and it probably won't even apply to master. We only apply selected bugfixes to release branches and then only as backports once the code has gone into master.
| |
| | |
| '''Split up longer patches''' into a patch series of logical code changes. Each change should compile and execute successfully. For instance, don't add a file to the makefile in patch one and then add the file itself in patch two. (This rule is here so that people can later use tools like "git bisect" without hitting points in the commit history where QEMU doesn't work for reasons unrelated to the bug they're chasing.)
| |
| | |
| '''Don't include irrelevant changes'''. In particular, don't include formatting, coding style or whitespace changes to bits of code that would otherwise not be touched by the patch. (It's OK to fix coding style issues in the immediate area (few lines) of the lines you're changing.) If you think a section of code really does need a reindent or other large-scale style fix, submit this as a separate patch which makes no semantic changes; don't put it in the same patch as your bug fix.
| |
| | |
| For smaller patches in less frequently changed areas of QEMU, '''consider using the [[Contribute/TrivialPatches|trivial patches]] process'''.
| |
| | |
| '''Write a good commit message'''. QEMU follows the usual standard for git commit messages: the first line (which becomes the email subject line) is "subsystem: single line summary of change". Then there is a blank line and a more detailed description of the patch, another blank and your Signed-off-by: line. Don't include comments like "This is a suggestion for fixing this bug" (they can go below the "---" line in the email so they don't go into the final commit message).
| |
| | |
| When replying to comments on your patches '''reply to all and not just the sender''' -- keeping discussion on the mailing list means everybody can follow it.
| |
| | |
| If you fix issues that are raised during review '''resend the entire patch series''' not just the one patch that was changed. This allows maintainers to easily apply the fixed series without having to manually identify which patches are relevant.
| |
| | |
| '''When resending patches add a v2/v3 suffix''' (eg [PATCH v2]). This means people can easily identify whether they're looking at the most recent version. (The first version of a patch need not say "v1", just [PATCH] is sufficient.) For patch series, the version applies to the whole series -- even if you only change one patch, you resend the entire series and mark it as "v2". Don't try to track versions of different patches in the series separately.
| |
| | |
| For later versions of patches '''include a summary of changes from previous versions, but not in the commit message itself'''. In an email formatted as a git patch, the commit message is the part above the "---" line, and this will go into the git changelog when the patch is committed. This part should be a self-contained description of what this version of the patch does, written to make sense to anybody who comes back to look at this commit in git in six months' time. The part below the "---" line and above the patch proper (git format-patch puts the diffstat here) is a good place to put remarks for people reading the patch email, and this is where the "changes since previous version" summary belongs.
| |
