1 [[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
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.
11 ## 1. Email subject format
13 The subject line has format:
15 [PATCH] one line summary
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.
21 ## 2. Email body contents: description
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
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.
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
38 ## 3. Email body contents: patch
40 ### Sub-Rule Number One:
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.
47 ### Sub-Rule Number Two:
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).
54 ### Sub-Rule Number Three:
56 Patch must be rooted one level above notmuch source tree. i.e.
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
63 or in other words, the patch must be apply-able using
65 patch -sp1 < foo.patch
67 ## 4. One patch per email
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
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.
81 ( currently notmuch in use )
83 ## 6. Avoid attachments and MIME
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
92 ## 7. Follow these instructions even when resending
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.
100 For more details, read Documentation/SubmittingPatches
101 in the linux kernel source tree.
104 ## Tips for producing and sending your patches.
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.
111 Then write your commit message with the rules above, i.e.
113 first commit line; one line description, up to 65 chars
115 after one empty line, a detailed description of your patch
116 the description most usually spans over multiple lines.
118 Now that you're committed your changes, enter
120 git format-patch HEAD^
122 This outputs something like
124 0001-one-line-description.patch
126 This is the file name of your patch with content:
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
133 after one empty line, a detailed description of your patch
134 the description most usually spans over multiple lines.
137 nn files changed, nn insertions(+) nn deletions(-)
139 diff --git a/<1st filename> b/<1st filename>
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.
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.
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
156 1. Start composing new mail
158 2. Enter notmuch mailing list address to To: field.
160 3. Go to the body part of the email
162 4. Enter C-x i (M-x insert-file) and insert the patch file to the buffer
164 5. Replace Subject: line from the Subject line of the patch.
166 6. Remove everything before the description content from the beginning of the body.
168 7. Fill the discussion part after `---` unless you have done so (and there is anything to discuss).
170 8. Check your text once more and then enter C-c C-c (message-send-and-exit).
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.