Contribute/SubmitAPullRequest

NB: this page is a draft work in progress and may not yet reflect consensus on the rules for pull requests.

QEMU welcomes contributions of code, but we generally expect these to be sent as simple patch emails to the mailing list (see our page on submitting a patch for more details). Generally only existing submaintainers of a tree will need to submit pull requests, although occasionally for a large patch series we might ask a submitter to send a pull request. This page documents our recommendations on pull requests for those people.

Retransmit the patches in the pull request as emails which are threaded as follow-ups to the pull request itself. The simplest way to do this is to use git format-patch --cover-letter to create the emails, and then edit the cover letter to include the pull request details that git request-pull outputs.

Use PULL as the subject line tag in both the cover letter and the retransmitted patch mails (for example, by using --subject-prefix=PULL in your git format-patch command). This helps people to filter in or out the resulting emails (especially useful if they are only CC'd on one email out of the set).

Each patch must have your own Signed-off-by: line as well as that of the original author if the patch was not written by you. This is because with a pull request you're now indicating that the patch has passed via you rather than directly from the original author.

Don't forget to add Reviewed-by: and Acked-by: lines. When other people have reviewed the patches you're putting in the pull request, make sure you've copied their signoffs across. (If you use Anthony's patches tool to add patches from email directly to your git repo it will include the tags automatically; if you're updating patches manually or in some other way you'll need to edit the commit messages by hand.)

Don't send pull requests for code that hasn't passed review. A pull request says these patches are ready to go into QEMU now, so they must have passed the standard code review processes. In particular if you've corrected issues in one round of code review, you need to send your fixed patch series as normal to the list; you can't put it in a pull request until it's gone through. (Extremely trivial fixes may be OK to just fix in passing, but if in doubt err on the side of not.)

Test before sending. This is an obvious thing to say, but make sure everything builds (including that it compiles at each step of the patch series) and that "make check" passes before sending out the pull request. As a submaintainer you're one of QEMU's lines of defense against bad code, so double check the details.