Signed-off-by: Johannes Löthberg <johannes@kyriasis.com> --- doc/Makefile.am | 6 ++- doc/submitting-patches.txt | 104 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 109 insertions(+), 1 deletion(-) create mode 100644 doc/submitting-patches.txt diff --git a/doc/Makefile.am b/doc/Makefile.am index b67c81d..b44319d 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -9,8 +9,12 @@ ASCIIDOC_MANS = \ HTML_MANPAGES = \ pactree.8.html +HTML_OTHER = \ + submitting-patches.html + HTML_DOCS = \ - $(HTML_MANPAGES) + $(HTML_MANPAGES) \ + $(HTML_OTHER) EXTRA_DIST = \ asciidoc.conf \ diff --git a/doc/submitting-patches.txt b/doc/submitting-patches.txt new file mode 100644 index 0000000..cbd8b60 --- /dev/null +++ b/doc/submitting-patches.txt @@ -0,0 +1,104 @@ +Submitting Patches +================== + +This document is here mainly to make the job of those who review patches easier +and is more of a guideline rather than a strict set of rules. However, please +try to follow them as much as you can. + + +Getting the most recent source +------------------------------ +Patches need to be submitted in Git format and are best if they are against the +latest version of the code. There are several helpful tutorials for getting +started with Git if you have not worked with it before. + +* https://git-scm.com/book +* https://www.kernel.org/pub/software/scm/git/docs/gittutorial.html + +The pacman-contrib code can be fetched using the following command: + + git clone git://projects.archlinux.org/pacman-contrib.git + + +Creating your patch +------------------- + +-- +* Use `git commit -s` for creating a commit of your changes. + +The -s allows you to credit yourself by adding a "Signed Off By" line to +indicate who has "signed" the patch - who has approved it. + + Signed-off-by: Aaron Griffin <aaron@archlinux.org> + +Please use your real name and email address. Feel free to "scramble" the +address if you're afraid of spam. + +* Describe your patch. + +It helps if you describe the overview and goals of the patch in the git commit +log. This allows others to see what you intended so as to compare it to what +was actually done, and allows better feedback. + +* Use `git format-patch` to create patches. + +Your commit message will be shown above the patch by default when you will use +`git format-patch`, including the signoff line. Sets of multiple patches that +need extra explanation beyond the commit messages may include additional notes +in a cover letter. Individual patches may include additional notes between the +"---" following the commit message and the beginning of the diff. + +-- + +Submitting your patch +--------------------- + +-- +* Send the patch to the https://lists.archlinux.org/listinfo/pacman-contrib[pacman-contrib] mailing list + +The mailing list is the primary queue for review and acceptance. Here you +will get feedback, and let the reviewers know the details of your patch. + +* No MIME, no links, no compression, no attachments. Just plain text. + +Patches should be contained in the actual body of the email. There are many +reasons for this. First, it makes them easier to read with any mail reader, +it allows easier review "at a glance", and most importantly, it allows people +to comment on exact lines of the patch in reply emails. + +`git send-email` allows you to send Git-formatted patches in plain text easily +and is the preferred method for submission to the mailing list. Mail clients, +including Gmail's web interface, have a tendency to break patches by wrapping +lines and/or adjusting whitespace and should be avoided. + +-- + +After you submit +---------------- + +-- +* Don't get discouraged + +Any feedback you get, positive or negative, has nothing to do with you. If a +patch is rejected, try taking the suggestions into account and re-submitting. +We welcome most submissions here, and some may take a bit longer to get +looked over than others. If you think your patch got lost in the shuffle, +send another email to the list in reply to the original asking if anyone has +looked at it yet. + +* Respond to feedback + +When you do get feedback, it usually merits a response, whether this be a +resubmission of the patch with corrections or a follow-up email asking for +clarifications. When neither of these occurs, don't expect your patch to get +further review. The all-volunteer staff don't have time to fix up patches that +aren't their own. When resubmitting patches, update the subject line to reflect +the version number ('[PATCHv2]'), and send it as a reply to the original +thread. When using `git format-patch` you can pass in e.g. -v2 to have it +automatically set the patch prefix appropriately. + +-- + +///// +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: +///// -- 2.16.2