1.. _submitting-a-pull-request: 2 3Submitting a Pull Request 4========================= 5 6QEMU welcomes contributions of code, but we generally expect these to be 7sent as simple patch emails to the mailing list (see our page on 8:ref:`submitting-a-patch` 9for more details). Generally only existing submaintainers of a tree 10will need to submit pull requests, although occasionally for a large 11patch series we might ask a submitter to send a pull request. This page 12documents our recommendations on pull requests for those people. 13 14A good rule of thumb is not to send a pull request unless somebody asks 15you to. 16 17**Resend the patches with the pull request** as emails which are 18threaded as follow-ups to the pull request itself. The simplest way to 19do this is to use ``git format-patch --cover-letter`` to create the 20emails, and then edit the cover letter to include the pull request 21details that ``git request-pull`` outputs. 22 23**Use PULL as the subject line tag** in both the cover letter and the 24retransmitted patch mails (for example, by using 25``--subject-prefix=PULL`` in your ``git format-patch`` command). This 26helps people to filter in or out the resulting emails (especially useful 27if they are only CC'd on one email out of the set). 28 29**Each patch must have your own Signed-off-by: line** as well as that of 30the original author if the patch was not written by you. This is because 31with a pull request you're now indicating that the patch has passed via 32you rather than directly from the original author. 33 34**Don't forget to add Reviewed-by: and Acked-by: lines**. When other 35people have reviewed the patches you're putting in the pull request, 36make sure you've copied their signoffs across. (If you use the `patches 37tool <https://github.com/stefanha/patches>`__ to add patches from email 38directly to your git repo it will include the tags automatically; if 39you're updating patches manually or in some other way you'll need to 40edit the commit messages by hand.) 41 42**Don't send pull requests for code that hasn't passed review**. A pull 43request says these patches are ready to go into QEMU now, so they must 44have passed the standard code review processes. In particular if you've 45corrected issues in one round of code review, you need to send your 46fixed patch series as normal to the list; you can't put it in a pull 47request until it's gone through. (Extremely trivial fixes may be OK to 48just fix in passing, but if in doubt err on the side of not.) 49 50**Test before sending**. This is an obvious thing to say, but make sure 51everything builds (including that it compiles at each step of the patch 52series) and that "make check" passes before sending out the pull 53request. As a submaintainer you're one of QEMU's lines of defense 54against bad code, so double check the details. 55 56**All pull requests must be signed**. By "signed" here we mean that 57the pullreq email should quote a tag which is a GPG-signed tag (as 58created with 'gpg tag -s ...'). See :ref:`maintainer_keys` for 59details. 60 61**Pull requests not for master should say "not for master" and have 62"PULL SUBSYSTEM whatever" in the subject tag**. If your pull request is 63targeting a stable branch or some submaintainer tree, please include the 64string "not for master" in the cover letter email, and make sure the 65subject tag is "PULL SUBSYSTEM s390/block/whatever" rather than just 66"PULL". This allows it to be automatically filtered out of the set of 67pull requests that should be applied to master. 68 69You might be interested in the `make-pullreq 70<https://git.linaro.org/people/peter.maydell/misc-scripts.git/tree/make-pullreq>`__ 71script which automates some of this process for you and includes a few 72sanity checks. Note that you must edit it to configure it suitably for 73your local situation! 74