doc/submitting-patches.txt

   1 Pacman - Submitting Patches
   2 ===========================
   3
   4 This document is here mainly to make the job of those who review patches
   5 easier and is more of a guideline and not a strict set of rules.  However,
   6 please try to follow as much as you can.
   7
   8 NOTE: Some of this is paraphrased from the kernel documentation's
   9 "SubmittingPatches" file.
  10
  11 Getting the most recent source
  12 ------------------------------
  13
  14 Patches need to be submitted in GIT format and are best if they are against the
  15 latest version of the code. There are several helpful tutorials for getting
  16 started with GIT if you have not worked with it before.
  17
  18 * http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html
  19 * http://wiki.archlinux.org/index.php/Super_Quick_Git_Guide
  20
  21 The pacman code can be fetched using the following command:
  22
  23     git clone git://projects.archlinux.org/pacman.git
  24
  25
  26 Creating your patch
  27 -------------------
  28
  29 --
  30 * use `git commit -s` for creating a commit of your changes.
  31
  32 The -s allows you to credit yourself by adding a "Signed Off By" line to
  33 indicate who has "signed" the patch - who has approved it.
  34
  35     Signed-off-by: Aaron Griffin <aaron@archlinux.org>
  36
  37 Please use your real name and email address. Feel free to "scramble" the
  38 address if you're afraid of spam.
  39
  40 * Describe your patch.
  41
  42 It helps if you describe the overview and goals  of the patch in the git commit
  43 log.  This allows others to see what you intended so as to compare it to what
  44 was actually done, and allows better feedback.
  45
  46 * Use `git format-patch` to create patches.
  47
  48 Your commit message will be shown above the patch by default when you will use
  49 `git-format-patch`, including the signoff line.
  50 --
  51
  52 Submitting your patch
  53 ---------------------
  54
  55 --
  56 * Send the patch to the pacman-dev mailing list
  57
  58 The mailing list is the primary queue for review and acceptance.  Here you
  59 will get feedback, and let me know the details of your patch.
  60
  61 * No MIME, no links, no compression, no attachments.  Just plain text.
  62
  63 Patches should be contained in the actual body of the email.  There are many
  64 reasons for this.  First, it makes them easier to read with any mail reader,
  65 it allows easier review "at a glance", and most importantly, it allows people
  66 to comment on exact lines of the patch in reply emails.
  67
  68 `git send-email` allows you to send git formatted patches in plain text easily
  69 and is the preferred method for submission to the mailing list.
  70
  71 --
  72
  73 After you submit
  74 ----------------
  75
  76 --
  77 * Don't get discouraged
  78
  79 Any feedback you get, positive or negative, has nothing to do with you.  If a
  80 patch is rejected, try taking the suggestions into account and re-submitting.
  81 We welcome most submissions here, and some may take a bit longer to get
  82 looked over than others. If you think your patch got lost in the shuffle,
  83 send another email to the list in reply to the original asking if anyone has
  84 looked at it yet.
  85
  86 * Respond to feedback
  87
  88 When you do get feedback, it usually merits a response, whether this be a
  89 resubmit of the patch with corrections or a follow-up email asking for
  90 clarifications. When neither of these occurs, don't expect your patch to see
  91 further review. The all-volunteer staff don't have time to fix up patches that
  92 aren't their own.
  93
  94 --
  95
  96 /////
  97 vim: set ts=2 sw=2 syntax=asciidoc et:
  98 /////