[libvirt PATCH 08/10] docs: Add submitting-patches.rst

This is a relatively lengthy part with lots of details, which many people who are familiar with a mail-based development workflow will already know and which will become obsolete once we move to GitLab. Move the contents to a separate page. Signed-off-by: Andrea Bolognani <abologna(a)redhat.com&gt; --- docs/hacking.rst | 85 ----------------------------------- docs/submitting-patches.rst | 88 +++++++++++++++++++++++++++++++++++++ 2 files changed, 88 insertions(+), 85 deletions(-) create mode 100644 docs/submitting-patches.rst diff --git a/docs/hacking.rst b/docs/hacking.rst index bf01c05928..abede5f206 100644 --- a/docs/hacking.rst +++ b/docs/hacking.rst @@ -21,91 +21,6 @@ General tips for contributing patches The libvirt release process automatically pulls the latest version of each translation file from zanata. -#. The simplest way to send patches is to use the - `git-publish <https://github.com/stefanha/git-publish>`__ - tool. All libvirt-related repositories contain a config file - that tells git-publish to use the correct mailing list and - subject prefix. - - Alternatively, you may send patches using ``git send-email``. - - Also, for code motion patches, you may find that - ``git diff --patience`` provides an easier-to-read - patch. However, the usual workflow of libvirt developer is: - - :: - - git checkout master - git pull - git checkout -t origin -b workbranch - Hack, committing any changes along the way - - More hints on compiling can be found `here <compiling.html>`__. - When you want to post your patches: - - :: - - git pull --rebase - (fix any conflicts) - git send-email --cover-letter --no-chain-reply-to --annotate \ - --confirm=always --to=libvir-list(a)redhat.com master - - For a single patch you can omit ``--cover-letter``, but a - series of two or more patches needs a cover letter. - - Note that the ``git send-email`` subcommand may not be in the - main git package and using it may require installation of a - separate package, for example the "git-email" package in Fedora - and Debian. If this is your first time using - ``git send-email``, you might need to configure it to point it - to your SMTP server with something like: - - :: - - git config --global sendemail.smtpServer stmp.youremailprovider.net - - If you get tired of typing ``--to=libvir-list(a)redhat.com`` all - the time, you can configure that to be automatically handled as - well: - - :: - - git config sendemail.to libvir-list(a)redhat.com - - As a rule, patches should be sent to the mailing list only: all - developers are subscribed to libvir-list and read it regularly, - so **please don't CC individual developers** unless they've - explicitly asked you to. - - Avoid using mail clients for sending patches, as most of them - will mangle the messages in some way, making them unusable for - our purposes. Gmail and other Web-based mail clients are - particularly bad at this. - - If everything went well, your patch should show up on the - `libvir-list - archives <https://www.redhat.com/archives/libvir-list/>`__ in a - matter of minutes; if you still can't find it on there after an - hour or so, you should double-check your setup. **Note that, if - you are not already a subscriber, your very first post to the - mailing list will be subject to moderation**, and it's not - uncommon for that to take around a day. - - Please follow this as close as you can, especially the rebase - and ``git send-email`` part, as it makes life easier for other - developers to review your patch set. - - One should avoid sending patches as attachments, but rather - send them in email body along with commit message. If a - developer is sending another version of the patch (e.g. to - address review comments), they are advised to note differences - to previous versions after the ``---`` line in the patch so - that it helps reviewers but doesn't become part of git history. - Moreover, such patch needs to be prefixed correctly with - ``--subject-prefix=PATCHv2`` appended to - ``git send-email`` (substitute ``v2`` with the - correct version if needed though). - #. In your commit message, make the summary line reasonably short (60 characters is typical), followed by a blank line, followed by any longer description of why your patch makes sense. If the diff --git a/docs/submitting-patches.rst b/docs/submitting-patches.rst new file mode 100644 index 0000000000..17b072655d --- /dev/null +++ b/docs/submitting-patches.rst @@ -0,0 +1,88 @@ +================== +Submitting patches +================== + +The simplest way to send patches is to use the +`git-publish <https://github.com/stefanha/git-publish>`__ +tool. All libvirt-related repositories contain a config file +that tells git-publish to use the correct mailing list and +subject prefix. + +Alternatively, you may send patches using ``git send-email``. + +Also, for code motion patches, you may find that +``git diff --patience`` provides an easier-to-read +patch. However, the usual workflow of libvirt developer is: + +:: + + $ git checkout master + $ git pull + $ git checkout -t origin -b workbranch + (hack, committing any changes along the way) + +More hints on compiling can be found `here <compiling.html>`__. +When you want to post your patches: + +:: + + $ git pull --rebase + (fix any conflicts) + $ git send-email --cover-letter --no-chain-reply-to --annotate \ + --confirm=always --to=libvir-list(a)redhat.com master + +For a single patch you can omit ``--cover-letter``, but a +series of two or more patches needs a cover letter. + +Note that the ``git send-email`` subcommand may not be in the +main git package and using it may require installation of a +separate package, for example the "git-email" package in Fedora +and Debian. If this is your first time using +``git send-email``, you might need to configure it to point it +to your SMTP server with something like: + +:: + + $ git config --global sendemail.smtpServer stmp.youremailprovider.net + +If you get tired of typing ``--to=libvir-list(a)redhat.com`` all +the time, you can configure that to be automatically handled as +well: + +:: + + $ git config sendemail.to libvir-list(a)redhat.com + +As a rule, patches should be sent to the mailing list only: all +developers are subscribed to libvir-list and read it regularly, +so **please don't CC individual developers** unless they've +explicitly asked you to. + +Avoid using mail clients for sending patches, as most of them +will mangle the messages in some way, making them unusable for +our purposes. Gmail and other Web-based mail clients are +particularly bad at this. + +If everything went well, your patch should show up on the +`libvir-list +archives <https://www.redhat.com/archives/libvir-list/>`__ in a +matter of minutes; if you still can't find it on there after an +hour or so, you should double-check your setup. **Note that, if +you are not already a subscriber, your very first post to the +mailing list will be subject to moderation**, and it's not +uncommon for that to take around a day. + +Please follow this as close as you can, especially the rebase +and ``git send-email`` part, as it makes life easier for other +developers to review your patch set. + +One should avoid sending patches as attachments, but rather +send them in email body along with commit message. If a +developer is sending another version of the patch (e.g. to +address review comments), they are advised to note differences +to previous versions after the ``---`` line in the patch so +that it helps reviewers but doesn't become part of git history. +Moreover, such patch needs to be prefixed correctly with +``--subject-prefix=PATCHv2`` appended to +``git send-email`` (substitute ``v2`` with the +correct version if needed though). -- 2.25.1