submitting-patches

   1 Pacman - Submitting Patches
   2 ===========================
   3
   4 This document is here mainly to make my job easier, and is more of a guideline,
   5 and not a strict set of rules.  Please try to follow as much as you can.
   6
   7 NOTE: Much of this is paraphrased from the kernel documentation's
   8 "SubmittingPatches" file.
   9
  10 Creating your patch
  11 -------------------
  12
  13 Most of this was more relevant before we switched to GIT for version control.
  14 However, much of it is still applicable and should be followed. Some notes
  15 have been added to make this a bit more up-to-date with the GIT workflow.
  16
  17 --
  18 * Use "diff -up" or "diff -uprN" to create patches.
  19
  20 These options make the diff easier to read for those of us who try to review
  21 submitted patches. If you are working on your own git branch, then GIT
  22 formatted patches are perfectly acceptable.
  23
  24 * Please try to make patches "p1 applicable"
  25
  26 This means that if you are patching file "lib/libalpm/alpm.h", I should be
  27 able to apply your patch while passing the -p1 argument to 'patch'.  The diff
  28 header should look like so:
  29
  30   --- ORIGINAL_DIR/lib/libalpm/alpm.h
  31   +++ NEW_DIR/lib/libalpm/alpm.h
  32
  33 With '-p1' the ORIGINAL_DIR and NEW_DIR arguments are stripped. GIT produces
  34 p1 formatted patches by default.
  35 --
  36
  37 Submitting your patch
  38 ---------------------
  39
  40 --
  41 * Send the patch to the pacman-dev mailing list
  42
  43 The mailing list is the primary queue for review and acceptance.  Here you
  44 will get feedback, and let me know the details of your patch.  It also helps
  45 if you add "[patch]" to the beginning of your Subject line.
  46
  47 * No MIME, no links, no compression, no attachments.  Just plain text.
  48
  49 Patches should be contained in the actual body of the email.  There are many
  50 reasons for this.  Firstly, it makes them easier to read with any mail reader,
  51 it allows easier review "at a glance", and most importantly, it allows people
  52 to comment on exact lines of the patch in reply emails.
  53
  54 It is important to know that the diff format ignores plain text before (and
  55 after) the main diff itself.  If you directly insert your patch into an email,
  56 you can safely add lines above it describing your patch.
  57
  58 * Describe your patch.
  59
  60 Before the actual diff begins, it helps if you describe the changes in the
  61 patch.  This allows others to see what you intended so as to compare it to
  62 what was actually done, and allows better feedback. If you use
  63 `git-format-patch` to create your patch, then your commit message will
  64 be shown above the patch by default.
  65
  66 * Credit yourself
  67
  68 Just like with the kernel, it helps if you add a "Signed Off By" line to
  69 indicate who has "signed" the patch - who has approved it.
  70
  71     Signed-off-by: Aaron Griffin <aaron@archlinux.org>
  72
  73
  74 Please use your real name and email address.  Feel free to "scramble" the
  75 address if you're afraid of spam. `git commit -s` makes this easy.
  76 --
  77
  78 After you submit
  79 ----------------
  80
  81 --
  82 * Don't get discouraged
  83
  84 Any feedback you get, positive or negative, has nothing to do with you.  If a
  85 patch is rejected, try taking the suggestions into account and re-submitting.
  86 We welcome most submissions here, and some may take a bit longer to get
  87 looked over than others. If you think your patch got lost in the shuffle,
  88 send another email to the list in reply to the original asking if anyone has
  89 looked at it yet.
  90 --
  91
  92 /////
  93 vim: set ts=2 sw=2 syntax=asciidoc et:
  94 /////