1 [[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
6 Before you intend to provide patches outside of your local circle
7 you should check the following:
9 1. Run `git log` and examine quite a few commit messages.
11 2. Read mailing list (archives) and follow the discussions on the patches sent.
13 3. Get familiar with coding conventions used.
15 This way you get some insight of the look and feel of the patches sent,
16 both the way code should be written, how to write commit log messages
17 and how to participate patch discussions.
19 ## Committing changes (locally)
21 After you've been editing your changes under cloned notmuch git repository
22 first commit your changes... preferably (to you) to a separate branch;
23 if you forgot to branch before starting you can do it now -- your modified
24 working tree will follow.
26 Enter your commit message in following format:
28 first commit line; short one line description
30 After one empty line, a detailed description of your changes
31 the description most usually spans over multiple lines.
33 Wrap the lines to about __72__ characters or so. On an 80 column terminal,
34 if we subtract 4 columns for the indent on the left and 4 more for
35 symmetry on the right, we’re left with __72__ columns.
37 Regarding the commit message body contents,
38 Carl [has stated](http://article.gmane.org/gmane.mail.notmuch.general/504):
40 > The single line summary is good about saying *what* the commit does,
41 > but I always want to see at least one sentence about the *why* as well.
43 ### Activating default pre-commit hook
45 Git provides a default pre-commit hook which, when activated, checks
46 (at least) for whitespace errors (trailing whitespace and space before
47 tab). It is better to notice this kind of "errors" early than have
48 patch reviewers to mention about those.
50 The hook, when activated, is named as .git/hooks/pre-commit and it
51 has execute permissions set on. By default, when git tree is cloned
52 your hooks dir may have default, inactive pre-commit hook available
55 1. .git/hooks/pre-commit without execute permission set
57 2. .git/hooks/pre-commit.sample usually with execute permission set
59 In case of 2, enter `cp .git/hooks/pre-commit.sample .git/hooks/pre-commit`.
60 And, now enter `chmod a+x .git/hooks/pre-commit` in case it does not
61 have execute permission set.
63 ## Remember: one patch per email
65 Every patch should (must!) contain only one bugfix or new feature.
67 Eric S. Raymond has written good
68 [Software Release Practice HOWTO](http://tldp.org/HOWTO/Software-Release-Practice-HOWTO/).
69 Check what he has to say about this issue.
71 ### Test Suite Enhancements
73 New features as well as bug fixes should typically come with test suite
74 enhancements. The test suite changes should be done first (tagged as *expected
75 to fail*), and the feature implementation or bug fix should come second
76 (removing the *expected to fail* tag). This way, the test suite specifies the
77 behavior you're trying to implement, be it a new feature or a bug fix. By
78 defining beforehand exactly what you expect to happen, everyone can confirm
79 that your patch achieves what it is meant it to.
81 ## Prepare patches for e-mail submission
83 If you've made just one commit (containing just one bugfix or new feature)
86 git format-patch HEAD^
88 This outputs something like
90 0001-one-line-description.patch
92 This is the file name of your patch with content:
94 From <-40-character-sha1-hexadecimal-string-> Day Mon DD HH:MM:SS YYYY
95 From: user.name <user.email>
96 Date: Day, DD Mon YYYY HH:MM:SS TZOFF
97 Subject: [PATCH] first commit line; one line description, up to 65 chars
99 after one empty line, a detailed description of your patch
100 the description most usually spans over multiple lines.
103 nn files changed, nn insertions(+) nn deletions(-)
105 diff --git a/<1st filename> b/<1st filename>
108 If you have committed more patches, and want to prepare all of those
109 you can check with `git log` a 40-char commit-sha1 of the last commit
110 *since* you want to generate patch files. When you enter
112 git format-patch <commit-sha1(-prefix)>
114 every commit *after* that commit-sha1 will be used to generate
117 ### Test-applying your patches
119 Sometimes you may face a situation with your patches that you are unsure
120 whether those patches apply to the origin. Such a cases might be:
122 * You've taken your patches from a branch that has some other commits on top of origin.
124 * You have edited the commit message, comments below commit message or the patch content itself in the patch files generated.
126 To verify that your patches will apply on top of pristine origin you can
127 test-apply your patch files on origin/master:
129 * Simple case -- no other changes on top of origin/master
131 git reset --hard origin/master
135 * A case where working tree is dirty
137 git log -1 --format=%H > head_commit
139 git reset --hard origin/master
143 git reset --hard `cat head_commit`
150 ### Using git send-email
152 (This is the preferred way)
154 If you try to execute `git send-email` and you get
156 git: 'send-email' is not a git command. See 'git --help'.
158 Then you're using git installation where send-email command is distributed
159 in separate package. In Debian/Ububtu/RedHat/Fedora the package is named
160 `git-email`. Use the package manager in your distribution to install this
161 package (or ask administrator to do this if you don't have privileges to do so).
163 Playing with `git send-email` is pretty safe. By default it will ask questions,
164 finally whether the email is to be sent or not. In normal cases you may
165 just need to set smtp server (in case local sendmail is not configured to
166 work properly). Check through `git-send-email` manual page and play with it.
168 In case of one-file you might want to use
170 git send-email --annotate 0001-*
172 (other options omitted) to add a 'discussion' part into your
173 email. The `git am` tool which is eventually used to submit the patch
174 will ignore anything after first `---` and before the `diff --git ...`
175 in the mail message (see example content above). In this case be careful
176 you don't break the commit log message or the patch content.
178 In case of multi-patch send, `git send-email --compose 00*.patch` can be
179 used to send an introductory message (as separate email). This also follows
180 the principle of sending only one patch per mail -- by sending each patch
183 After you've played (perhaps with `--dry-run`) a bit, send first test emails
184 to your own email address to see how the messages appear in your mailbox.
185 In this phase you can "streamline" your `git send-email` options for
186 actual patch sending to the mailing list.
188 ### Sending one patch using compatible (emacs) email client.
190 Sometimes using git-send-email is not possible; It is not installed by
191 default and you don't have privileges to install it or you are not
192 able to compile it as it has more build-time requirements as git itself.
194 One alternative way to send your patches is to use, for example, the
195 emacs mail client you've already used to send mails to mailing list.
196 In this case you have to be very careful to keep the patch contents
199 1. Start composing new mail
201 2. Enter notmuch mailing list address into To: field.
203 3. Go to the body part of the email
205 4. Enter `C-x i` (M-x insert-file) and insert the patch file to the buffer
207 5. Replace Subject: line from the Subject line of the patch.
209 6. Remove everything before the description content from the beginning of the body.
211 7. Fill the discussion part after `---` unless you have done so (and there is anything to discuss).
213 8. Check your text once more and then enter `C-c C-c` (message-send-and-exit).
215 When your patches appear on the mailing list read the comments and take part
216 to the discussion and prepare to do adjustments to your patches.