1 [[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
2 # Contributing to Notmuch
4 This is your friendly guide to contributing to Notmuch. In a nutshell,
5 the Notmuch project maintains fairly high standards for code, review,
6 tests, and documentation. It may seem a bit intimidating at first, and
7 you may find it difficult to get your first contributions accepted,
8 but once you get the hang of it, it'll be fun. This page should help
9 you get there. DON'T PANIC.
11 The headlines below act as a checklist. Not all of them apply in all
12 situations; use common sense.
16 ## Obtain the Notmuch source code
18 The Notmuch source code is maintained in [git](http://git-scm.com/). Get the
21 git clone git://notmuchmail.org/git/notmuch
23 This guide assumes a working knowledge of git. There are plenty of resources
24 available on git, such as [Pro Git](http://git-scm.com/book) and the git man
25 pages. Please refer to them as necessary.
29 The changes you submit should almost always be based on the current
30 Notmuch git master. There are plenty of ways to work in git, and this
31 is not your git guide, but a typical workflow might start with:
34 git checkout -b my-local-branch origin/master
39 If you're planning big changes, it may be advisable to __not__ polish
40 the patch series according to all the details described below at
41 first. Instead, it may save everyone's time to introduce the idea
42 using draft or work-in-progress patches, and get the design right from
43 the beginning. Add a cover letter explaining what you want to
44 achieve. You may prefix the subjects of such patches with "RFC" or
47 ## Pay attention to the Notmuch coding style
49 The Notmuch code base follows a fairly uniform coding style. See the existing
50 code around your changes, and read
51 [`devel/STYLE`](http://git.notmuchmail.org/git/notmuch/blob/HEAD:/devel/STYLE)
52 in the Notmuch source. It's not difficult to get it right, and may save you an
55 ## Split your commits in logical chunks
57 Each commit should contain one logical change only. The code should
58 build and the tests should pass after each commit. Changes to lib,
59 cli, emacs, tests, man pages, or news are usually best kept
60 separate. Also separate cleanups from functional changes. See the
61 Notmuch source history (**`git log`**) for examples.
63 For in-depth discussion on the subject, see
64 [Software Release Practice HOWTO](http://tldp.org/HOWTO/Software-Release-Practice-HOWTO/) by Eric S. Raymond.
66 ## Write meaningful commit messages
68 [Quoting Carl](http://article.gmane.org/gmane.mail.notmuch.general/504),
69 "The single line summary is good about saying what the commit does,
70 but I always want to see at least one sentence about the why as well."
73 [Pro Git](http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines)
74 on commit guidelines, including commit messages.
76 It is customary to prefix the subject line with "lib:", "cli:", "emacs:",
77 etc. depending on which part of Notmuch the commit is changing. See
78 **`git log`** for examples.
80 Wrap the lines to about 72 characters.
82 If you want to share notes that shall not become part of the commit
83 message when applied to the upstream Notmuch repository, add the notes
84 at the end, after a line containing "---".
86 ## Update the test suite
88 Notmuch has a test suite with fairly good coverage. At the very least, `make
89 test` must pass after your changes. Therefore you must amend the tests if you
90 make functional changes that have existing test coverage. Preferably, you
91 should add new tests for any new functionality, and it helps in getting your
94 If you're fixing a bug, it is recommended to add a "known broken" test
95 highlighting the issue in a first patch, and then fix the bug (and remove
96 the known broken mark on the test) in the next patch in the series. This
98 easy to confirm your changes actually fix the issue. Some people use this
99 approach also for adding new features.
102 [`test/README`](http://git.notmuchmail.org/git/notmuch/blob/HEAD:/test/README)
103 in the Notmuch source for further information.
105 ## Update the documentation
107 If you modify or add new features to the Notmuch command-line tools,
108 you should update the manual pages under the `man` directory of the
111 If you modify or add new features to the Notmuch Emacs UI, you should
112 update the Emacs documentation.
116 If you make user visible changes, you should add an entry to the
117 [`NEWS`](http://git.notmuchmail.org/git/notmuch/blob/HEAD:/NEWS) file.
119 ## Update command-line completion
121 If you modify or add new features to the Notmuch command-line tools, it
122 would be a nice bonus if you also updated the Notmuch command-line
123 completion scripts under the `completion` directory of the Notmuch
124 source. Not required, but nice to have, and definitely can be done
127 ## Subscribe to the Notmuch mailing list
129 While strictly not required, it is advisable to subscribe to the
130 [Notmuch mailing list](http://notmuchmail.org/mailman/listinfo/notmuch)
131 before submitting patches.
133 ## Send your patches to the mailing list
135 Changes to Notmuch are contributed as [emailed
136 patches](http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Public-Large-Project).
137 Once you have your changes ready in your local repository, you need to
138 send them to the Notmuch mailing list. The simplest way is to use `git
139 send-email` to send the patches directly from your repository:
141 git send-email --to notmuch@notmuchmail.org origin/master
143 An alternative is to do this in two steps; first generating patch
144 files (using `git format-patch`), and then sending the patch files to
145 the mailing list (using `git send-email` or a mail client):
147 git format-patch origin/master
148 git send-email --to notmuch@notmuchmail.org *.patch
150 Either way, using `git send-email` to actually send the patches is
151 recommended. It may be distributed separately from git, typically in a
152 package named `git-email`.
154 ## Write a cover letter
156 If you are submitting a non-trivial set of patches, or if there's any
157 extra information you want to share that is not really part of the
158 commit messages, it is advisable to write a cover letter to give an
159 overview of your work. See the
160 [Notmuch mailing list archives](http://notmuchmail.org/pipermail/notmuch/)
161 for examples. Use the `--cover-letter` option of `git format-patch`,
162 or `--compose` option of `git send-email`.
164 ## Tag your patches in nmbug
166 When you're developing an email tool, all the problems start looking
167 like email. This applies to patch and bug tracking as well. The
168 Notmuch project uses [nmbug](http://notmuchmail.org/nmbug/) for
169 tracking. The Notmuch developers will tag your patches too, making
171 [nmbug status page](http://nmbug.tethera.net/status/), but requesting
172 access and tagging your patches yourself will be helpful in the long
175 ## Address review comments, participate in discussion
177 Each change to Notmuch must be peer reviewed before it is accepted,
178 usually by one or two developers, depending on the impact of the
179 changes. You are expected to follow up on the review comments you
180 receive, either by discussing the comments and the code, or modifying
181 your patches. Again, see the [Notmuch mailing list
182 archives](http://notmuchmail.org/pipermail/notmuch/) for examples.
184 ## Send another round addressing review comments
186 If your patches need to be changed based on review (they usually do),
187 you need to make the changes and re-submit. `git rebase -i` is your
188 friend in updating your series. Also note that the upstream master may
189 have changed; be sure to rebase your updated changes on top of the
192 Once you have the updated series ready, send it to the mailing list
193 again. It will be helpful for others to use the
194 `--subject-prefix="PATCH vN"` option of `git format-patch` or
195 `git send-email` to add a version number of the patch series to the
196 subject (replacing vN with v2, v3, etc.) Use a cover letter (or, in
197 the case of a single patch, the notes after a "---" at the end of the
198 commit message) to summarize the main changes since the previous
199 version of the patch series. Also include the message-id reference of
200 the previous version.
202 Using the `--in-reply-to` option of `git format-patch` or
203 `git send-email` to send the patch series as a reply to the earlier
204 version is generally discouraged, particularly for large series, but
205 there are no hard rules. Usually the message-id reference to the
206 previous version is sufficient and preferred.
208 Tag the old patches obsolete in [nmbug](http://notmuchmail.org/nmbug/)
211 ## Review other people's work
213 You scratch my back and I'll scratch yours. It will be easier to get
214 people to review your patches if you review theirs.
218 Send bug reports to the Notmuch mailing list. Preferably prefix the
219 subject line with "BUG:" or similar. Tag the message as a bug in
220 [nmbug](http://notmuchmail.org/nmbug/).
222 Even better, send a patch adding a "known broken" test to the test suite
223 highlighting the issue.
225 ## Update the Notmuch website
227 Update the Notmuch website, especially if you've landed a commit that
228 changes or obsoletes information on the site. It's a wiki; see the
229 [[instructions on how to edit the wiki|wikiwriteaccess]].
231 ## Join the Notmuch IRC channel
233 Patch review happens on the Notmuch mailing list, but there is plenty of
234 discussion going on in the freenode #notmuch IRC channel. See
235 [freenode.net/irc_servers.shtml](http://freenode.net/irc_servers.shtml)
236 for information how to get there.