git.cworth.org Git - notmuch-wiki/blob - patchformatting.mdwn

   1 [[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
   2 # Patch Formatting
   3
   4 This text is mostly based on
   5 [http://linux.yyz.us/patch-format.html](http://linux.yyz.us/patch-format.html);
   6  here modified to the simplest case possible that is suitable in this
   7 software. `git format-patch` produces base for this kind of patches.
   8 See mailing list archives for somewhat more complex scenarios.  At the
   9 end there are some tips how to get your patches sent.
  10
  11 ## 1. Email subject format
  12
  13 The subject line has format:
  14
  15       [PATCH] one line summary
  16
  17 I.e: a constant prefix `[PATCH]` followed by one line summary. The
  18 65-character limit seems to be common among many projects so that
  19 is good guideline to follow here too.
  20
  21 ## 2. Email body contents: description
  22
  23 At the beginning of your email, use as many lines as you wish to
  24 describe the patch. This text is copied directly into the SCM
  25 (i.e. git) changelog.
  26
  27 Include comments and other data (such as diffstat) you don't wish to
  28 be in the kernel changelog following a `---` terminator line. The
  29 terminator must be on a line by itself.
  30
  31 If you run `git log` on your cloned notmuch repository you see how log
  32 messages get structured from Subject: line and body contents. One
  33 description line, one empty line and then, usually multiline description
  34 following. Conversely, notmuch-wiki git log messages are often just one
  35 line long -- as the description (and the reasoning for it) is usually
  36 the content itself.
  37
  38 ## 3. Email body contents: patch
  39
  40 ### Sub-Rule Number One:
  41
  42 Patches must be reviewable in a standard Linux email client. This
  43 means in particular, no compression and no base64
  44 encoding. Attachments are discouraged, but some corporate mail systems
  45 provide no other way to send patches.
  46
  47 ### Sub-Rule Number Two:
  48
  49 Patch must be apply-able by a script that has no knowledge of [MIME]
  50 encoding. You must make sure your mailer does not escape standard
  51 US-ASCII characters, wrap long lines, or encode plaintext patches in
  52 base64 (or any other encoding).
  53
  54 ### Sub-Rule Number Three:
  55
  56 Patch must be rooted one level above notmuch source tree. i.e.
  57
  58       diff --git a/emacs/notmuch-mua.el b/emacs/notmuch-mua.el
  59       index 556d2bf..274c5da 100644
  60       --- a/emacs/notmuch-mua.el
  61       +++ b/emacs/notmuch-mua.el
  62
  63 or in other words, the patch must be apply-able using
  64
  65       patch -sp1 < foo.patch
  66
  67 ## 4. One patch per email
  68
  69 This cannot be stressed enough. Even when you are resending a change
  70 for the 5th time, resist the urge to attach 20 patches to a single
  71 email. If you do send multiple emails, make sure the second and
  72 subsequent emails are sent as replies to the first, to keep them all
  73 together in a thread.
  74
  75 The mailing list archive & the above link to linux patch formatting
  76 guidelines are good source of information how to format more complex
  77 subject line for set of related patches.
  78
  79 ## 5. Sign your work
  80
  81 ( currently notmuch in use )
  82
  83 ## 6. Avoid attachments and MIME
  84
  85 Attachments make it more difficult to review and comment on your
  86 patches. MIME (the mechanism by which files are attached to an email)
  87 has historically created a problem for patch import scripts. Some
  88 unfortunate email programs insist upon base64 encoding for all
  89 attachments, which completely shrouds the patch to some scripts and
  90 mailers.
  91
  92 ## 7. Follow these instructions even when resending
  93
  94 Quite often, when a patch receives comments, the patch author will
  95 (deep in an email thread) include a revised version of their patch but
  96 omit the email subject one-line summary, and overall patch
  97 description. This isn't script friendly, and requires the patch
  98 description to be hand-edited.
  99
 100 For more details, read Documentation/SubmittingPatches
 101 in the linux kernel source tree.
 102
 103
 104 ## Tips for producing and sending your patches.
 105
 106 After you've been editing your changes under cloned notmuch git repository
 107 first commit your changes... preferably (to you) to a separate branch;
 108 if you forgot to branch before starting you can do it now -- your modified
 109 working tree will follow.
 110
 111 Then write your commit message with the rules above, i.e.
 112
 113       first commit line; one line description, up to 65 chars
 114
 115       after one empty line, a detailed description of your patch
 116       the description most usually spans over multiple lines.
 117
 118 Now that you're committed your changes, enter
 119
 120       git format-patch HEAD^
 121
 122 This outputs something like
 123
 124       0001-one-line-description.patch
 125
 126 This is the file name of your patch with content:
 127
 128       From <-40-character-sha1-hexadecimal-string-> Day Mon DD HH:MM:SS YYYY
 129       From: user.name <user.email>
 130       Date: Day, DD Mon YYYY HH:MM:SS TZOFF
 131       Subject: [PATCH] first commit line; one line description, up to 65 chars
 132
 133       after one empty line, a detailed description of your patch
 134       the description most usually spans over multiple lines.
 135       ---
 136        <diffstat lines>
 137        nn files changed, nn insertions(+) nn deletions(-)
 138
 139       diff --git a/<1st filename> b/<1st filename>
 140       ...
 141
 142 Now, after that `---` line and before first `diff --git ...` line
 143 any discussion about the patch can be started by the patch supplier;
 144 those lines are ignored by `git am` tool which is (eventually) used to
 145 apply the patch to the repository.
 146
 147 If you have `git send-email` command available (and you can send emails
 148 from any of your shell accounts) you can use that to send your patches.
 149 Read the `git-send-email` manual page for information how to do so.
 150
 151 One alternative way to send your patches is to use, for example, the
 152 emacs mail client you've already used to send mails to notmuch mailing list.
 153 In this case you have to be very careful to keep the patch contents
 154 unchanged:
 155
 156 1. Start composing new mail
 157
 158 2. Enter notmuch mailing list address to To: field.
 159
 160 3. Go to the body part of the email
 161
 162 4. Enter C-x i (M-x insert-file) and insert the patch file to the buffer
 163
 164 5. Replace Subject: line from the Subject line of the patch.
 165
 166 6. Remove everything before the description content from the beginning of the body.
 167
 168 7. Fill the discussion part after `---` unless you have done so (and there is anything to discuss).
 169
 170 8. Check your text once more and then enter C-c C-c (message-send-and-exit).
 171
 172 When your patches appear on the mailing list read the comments and take part
 173 to the discussion and prepare to do adjustments to your patches.