docs/devel/submitting-a-pull-request.rst

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