From 0ff0dcf6b5292e044985c38cbd83a57485ca887c Mon Sep 17 00:00:00 2001 From: Kashyap Chamarthy Date: Wed, 10 Nov 2021 15:49:01 +0100 Subject: [PATCH] docs: rSTify the "SubmitAPullRequest" wiki MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The original wiki is here[1]. I converted by copying the wiki source into a .wiki file and convert to rST using `pandoc`: $ pandoc -f Mediawiki -t rst submitting-a-pull-request.wiki \ -o submitting-a-pull-request.rst This is a 1-1 conversion; no content changes. [1] https://wiki.qemu.org/Contribute/SubmitAPullRequest Signed-off-by: Kashyap Chamarthy Reviewed-by: Philippe Mathieu-Daudé Message-Id: <20211110144902.388183-3-kchamart@redhat.com> Signed-off-by: Thomas Huth --- docs/devel/index.rst | 1 + docs/devel/submitting-a-pull-request.rst | 76 ++++++++++++++++++++++++ 2 files changed, 77 insertions(+) create mode 100644 docs/devel/submitting-a-pull-request.rst diff --git a/docs/devel/index.rst b/docs/devel/index.rst index dbde1c44e9..211f8876da 100644 --- a/docs/devel/index.rst +++ b/docs/devel/index.rst @@ -46,3 +46,4 @@ modifying QEMU's source code. qapi-code-gen writing-monitor-commands trivial-patches + submitting-a-pull-request diff --git a/docs/devel/submitting-a-pull-request.rst b/docs/devel/submitting-a-pull-request.rst new file mode 100644 index 0000000000..8729d29036 --- /dev/null +++ b/docs/devel/submitting-a-pull-request.rst @@ -0,0 +1,76 @@ +Submit a Pull Request +===================== + +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. + +A good rule of thumb is not to send a pull request unless somebody asks +you to. + +**Resend the patches with 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 the `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. + +**All pull requests must be signed**. If your key is not already signed +by members of the QEMU community, you should make arrangements to attend +a `KeySigningParty `__ (for +example at KVM Forum) or make alternative arrangements to have your key +signed by an attendee. Key signing requires meeting another community +member \*in person\* so please make appropriate arrangements. By +"signed" here we mean that the pullreq email should quote a tag which is +a GPG-signed tag (as created with 'gpg tag -s ...'). + +**Pull requests not for master should say "not for master" and have +"PULL SUBSYSTEM whatever" in the subject tag**. If your pull request is +targeting a stable branch or some submaintainer tree, please include the +string "not for master" in the cover letter email, and make sure the +subject tag is "PULL SUBSYSTEM s390/block/whatever" rather than just +"PULL". This allows it to be automatically filtered out of the set of +pull requests that should be applied to master. + +You might be interested in the `make-pullreq +`__ +script which automates some of this process for you and includes a few +sanity checks. Note that you must edit it to configure it suitably for +your local situation!