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, the
5 Notmuch project maintains fairly high standards for code, review, tests, and
6 documentation. It may seem a bit intimidating at first, and you may find it
7 difficult to get your first contributions accepted, but once you get the hang of
8 it, it'll be fun. This page should help you get there. DON'T PANIC.
10 The headlines below act as a checklist. Not all of them apply in all situations;
15 ## Obtain the Notmuch source code
17 The Notmuch source code is maintained in [git](http://git-scm.com/). Get the
20 git clone git://notmuchmail.org/git/notmuch
22 This guide assumes a working knowledge of git. There are plenty of resources
23 available on git, such as [Pro Git](http://git-scm.com/book) and the git man
24 pages. Please refer to them as necessary.
28 The changes you submit should almost always be based on the current Notmuch git
29 master. There are plenty of ways to work in git, and this is not your git guide,
30 but a typical workflow might start with:
33 git checkout -b my-local-branch origin/master
38 If you're planning big changes, it may be advisable to __not__ polish the patch
39 series according to all the details described below at first. Instead, it may
40 save everyone's time to introduce the idea using draft or work-in-progress
41 patches, and get the design right from the beginning. Add a cover letter
42 explaining what you want to achieve. You may prefix the subjects of such patches
43 with "RFC" or "DRAFT" if you like.
45 ## Pay attention to the Notmuch coding style
47 The Notmuch code base follows a fairly uniform coding style. See the existing
48 code around your changes, and read
49 [`devel/STYLE`](http://git.notmuchmail.org/git/notmuch/blob/HEAD:/devel/STYLE)
50 in the Notmuch source. It's not difficult to get it right, and may save you an
53 ## Split your commits in logical chunks
55 Each commit should contain one logical change only. The code should build and
56 the tests should pass after each commit. Changes to lib, cli, emacs, tests,
58 are usually best kept separate. Also separate cleanups from functional
59 changes. See the Notmuch source history (`git log`) for examples.
61 For in-depth discussion on the subject, see
62 [Software Release Practice HOWTO](http://tldp.org/HOWTO/Software-Release-Practice-HOWTO/) by Eric S. Raymond.
64 ## Write meaningful commit messages
66 [Quoting Carl](http://article.gmane.org/gmane.mail.notmuch.general/504), "The
67 single line summary is good about saying what the commit does, but I always want
68 to see at least one sentence about the why as well."
70 See also [Pro Git](http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines) on commit guidelines, including commit messages.
72 It is customary to prefix the subject line with "lib:", "cli:", "emacs:",
73 etc. depending on which part of Notmuch the commit is changing. See `git log`
76 Wrap the lines to about 72 characters.
78 If you want to share notes that shall not become part of the commit message when
79 applied to the upstream Notmuch repository, add the notes at the end, after a
80 line containing "---".
82 ## Update the test suite
84 Notmuch has a test suite with fairly good coverage. At the very least, `make
85 test` must pass after your changes. Therefore you must amend the tests if you
86 make functional changes that have existing test coverage. Preferrably, you
87 should add new tests for any new functionality, and it helps in getting your
90 If you're fixing a bug, it is recommended to add a "known broken" test
91 highlighting the issue in a first patch, and then fix the bug (and remove
92 the known broken mark on the test) in the next patch in the series. This
94 easy to confirm your changes actually fix the issue. Some people use this
95 approach also for adding new features.
98 [`test/README`](http://git.notmuchmail.org/git/notmuch/blob/HEAD:/test/README)
99 in the Notmuch source for further information.
101 ## Update the documentation
103 If you modify or add new features to the Notmuch command-line tools, you should
104 update the manual pages under the `man` directory of the Notmuch source.
106 If you modify or add new features to the Notmuch Emacs UI, you should update the
111 If you make user visible changes, you should add an entry to the
112 [`NEWS`](http://git.notmuchmail.org/git/notmuch/blob/HEAD:/NEWS) file.
114 ## Subscribe to the Notmuch mailing list
116 While strictly not required, it is advisable to subscribe to the
117 [Notmuch mailing list](http://notmuchmail.org/mailman/listinfo/notmuch) before
120 ## Send your patches to the mailing list
122 Changes to Notmuch are contributed as
123 [emailed patches](http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Public-Large-Project). Once
124 you have your changes ready in your local repository, you need to send them to
125 the Notmuch mailing list. The simplest way is to use `git send-email` to send
126 the patches directly from your repository:
128 git send-email --to notmuch@notmuchmail.org origin/master
130 An alternative is to do this in two steps; first generating patch files (using
131 `git format-patch`), and then sending the patch files to the mailing list (using
132 `git send-email` or a mail client):
134 git format-patch origin/master
135 git send-email --to notmuch@notmuchmail.org *.patch
137 Either way, using `git send-email` to actually send the patches is
138 recommended. It may be distributed separately from git, typically in a package
141 ## Write a cover letter
143 If you are submitting a non-trivial set of patches, or if there's any extra
144 information you want to share that is not really part of the commit messages, it
145 is advisable to write a cover letter to give an overview of your work. See the
146 [Notmuch mailing list archives](http://notmuchmail.org/pipermail/notmuch/) for
147 examples. Use the `--cover-letter` option of `git format-patch`, or `--compose`
148 option of `git send-email`.
150 ## Tag your patches in nmbug
152 When you're developing an email tool, all the problems start looking like
153 email. This applies to patch and bug tracking as well. The Notmuch project uses
154 [nmbug](http://notmuchmail.org/nmbug/) for tracking. The Notmuch developers will
155 tag your patches too, making them show up in the
156 [nmbug status page](http://nmbug.tethera.net/status/), but requesting access and
157 tagging your patches yourself will be helpful in the long run.
159 ## Address review comments, participate in discussion
161 Each change to Notmuch must be peer reviewed before it is accepted, usually by
162 one or two developers, depending on the impact of the changes. You are expected
163 to follow up on the review comments you receive, either by discussing the
164 comments and the code, or modifying your patches. Again, see the
165 [Notmuch mailing list archives](http://notmuchmail.org/pipermail/notmuch/) for
168 ## Send another round addressing review comments
170 If your patches need to be changed based on review (they
171 usually do), you need to make the changes and re-submit. `git rebase -i` is your
172 friend in updating your series. Also note that the upstream master may have
173 changed; be sure to rebase your updated changes on top of the current master.
175 Once you have the updated series ready, send it to the mailing list again. It
176 will be helpful for others to use the `--subject-prefix="PATCH vN"` option of
177 `git format-patch` or `git send-email` to add a version number of the patch
178 series to the subject
179 (replacing vN with v2, v3, etc.) Use a cover letter (or, in the case of a single
180 patch, the notes after a "---" at the end of the commit message) to summarize
181 the main changes since the previous version of the patch series. Also include
182 the message-id reference of the previous version.
184 Using the `--in-reply-to` option of `git format-patch` or `git send-email` to
185 send the patch series as a reply to the earlier version is generally
186 discouraged, particularly for large series, but there are no hard rules. Usually
187 the message-id reference to the previous version is sufficient and preferred.
189 Tag the old patches obsolete in [nmbug](http://notmuchmail.org/nmbug/) if you
192 ## Review other people's work
194 You scratch my back and I'll scratch yours. It will be easier to get people to
195 review your patches if you review theirs.
199 Send bug reports to the Notmuch mailing list. Preferrably prefix the subject
200 line with "BUG:" or similar. Tag the message as a bug in
201 [nmbug](http://notmuchmail.org/nmbug/).
203 Even better, send a patch adding a "known broken" test to the test suite
204 highlighting the issue.
206 ## Join the Notmuch IRC channel
208 Patch review happens on the Notmuch mailing list, but there is plenty of
209 discussion going on in the freenode #notmuch IRC channel. See
210 http://freenode.net/irc_servers.shtml for more information.