Disambiguate Debian notmuch package and notmuch for emacs package.
[notmuch-wiki] / contributing.mdwn
1 [[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
2 # Contributing to Notmuch
3
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.
10
11 The headlines below act as a checklist. Not all of them apply in all
12 situations. Use your best judgment, and the Notmuch community will
13 help out as needed.
14
15 [[!toc levels=2]]
16
17 ## Obtain the Notmuch source code
18
19 The Notmuch source code is maintained in [git](http://git-scm.com/). Get the
20 source code using:
21
22         git clone https://git.notmuchmail.org/git/notmuch
23
24 This guide assumes a working knowledge of git. There are plenty of resources
25 available on git, such as [Pro Git](http://git-scm.com/book) and the git man
26 pages. Please refer to them as necessary.
27
28 ## Make your changes
29
30 The changes you submit should almost always be based on the current
31 Notmuch git master. There are plenty of ways to work in git, and this
32 is not your git guide, but a typical workflow might start with:
33
34         git fetch origin
35         git checkout -b my-local-branch origin/master
36         # make changes
37         git add ...
38         git commit
39
40 If you're planning big changes, it may be advisable to __not__ polish
41 the patch series according to all the details described below at
42 first. Instead, it may save everyone's time to introduce the idea
43 using draft or work-in-progress patches, and get the design right from
44 the beginning. Add a cover letter explaining what you want to
45 achieve. You may prefix the subjects of such patches with "RFC" or
46 "DRAFT" if you like.
47
48 ## Pay attention to the Notmuch coding style
49
50 The Notmuch code base follows a fairly uniform coding style. See the existing
51 code around your changes, and read
52 [`devel/STYLE`](https://git.notmuchmail.org/git/notmuch/blob/HEAD:/devel/STYLE)
53 in the Notmuch source. It's not difficult to get it right, and may save you an
54 extra review round.
55
56 ## Split your commits in logical chunks
57
58 Each commit should contain one logical change only. The code should
59 build and the tests should pass after each commit. Changes to lib,
60 cli, emacs, tests, man pages, or news are usually best kept
61 separate. Also separate cleanups from functional changes. See the
62 Notmuch source history (`git log`) for examples.
63
64 For in-depth discussion on the subject, see
65 [Software Release Practice HOWTO](http://tldp.org/HOWTO/Software-Release-Practice-HOWTO/) by Eric S. Raymond.
66
67 ## Write meaningful commit messages
68
69 [Quoting Carl](http://article.gmane.org/gmane.mail.notmuch.general/504),
70 "The single line summary is good about saying what the commit does,
71 but I always want to see at least one sentence about the why as well."
72
73 See also
74 [Pro Git](http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines)
75 on commit guidelines, including commit messages.
76
77 It is customary to prefix the subject line with "lib:", "cli:", "emacs:",
78 etc. depending on which part of Notmuch the commit is changing. See `git log`
79 for examples.
80
81 Wrap the lines to about 72 characters.
82
83 If you want to share notes that shall not become part of the commit
84 message when applied to the upstream Notmuch repository, add the notes
85 at the end, after a line containing "---".
86
87 ## Update the test suite
88
89 Notmuch has a test suite with fairly good coverage. At the very least, `make
90 test` must pass after your changes. Therefore you must amend the tests if you
91 make functional changes that have existing test coverage. Preferably, you
92 should add new tests for any new functionality, and it helps in getting your
93 changes accepted.
94
95 If you're fixing a bug, it is recommended to add a "known broken" test
96 highlighting the issue in a first patch, and then fix the bug (and remove
97 the known broken mark on the test) in the next patch in the series. This
98 makes it
99 easy to confirm your changes actually fix the issue. Some people use this
100 approach also for adding new features.
101
102 See
103 [`test/README`](https://git.notmuchmail.org/git/notmuch/blob/HEAD:/test/README)
104 in the Notmuch source for further information.
105
106 ## Update the documentation
107
108 If you modify or add new features to the Notmuch command-line tools,
109 you should update the manual pages under the `doc` directory of the
110 Notmuch source.
111
112 If you modify or add new features to the Notmuch Emacs UI, you should
113 update the Emacs documentation.
114
115 If you add a new keybinding, update `devel/emacs-keybindings.org`. As
116 much as possible, try to be consistent between modes.
117
118 ## Update NEWS
119
120 If you make user visible changes, you should add an entry to the
121 [`NEWS`](https://git.notmuchmail.org/git/notmuch/blob/HEAD:/NEWS) file.
122
123 In practice adding NEWS items can be done later during the release
124 process, but then you typically get a one line mention, if at all.
125
126 ## Update command-line completion
127
128 If you modify or add new features to the Notmuch command-line tools, it
129 would be a nice bonus if you also updated the Notmuch command-line
130 completion scripts under the `completion` directory of the Notmuch
131 source. Not required, but nice to have, and definitely can be done
132 afterwards.
133
134 ## Subscribe to the Notmuch mailing list
135
136 While strictly not required, it is advisable to subscribe to the
137 [Notmuch mailing list](https://nmbug.notmuchmail.org/list/)
138 before submitting patches.
139
140 ## Send your patches to the mailing list
141
142 Changes to Notmuch are contributed as [emailed
143 patches](http://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#Public-Project-over-Email).
144 Once you have your changes ready in your local repository, you need to
145 send them to the Notmuch mailing list. The simplest way is to use `git
146 send-email` to send the patches directly from your repository:
147
148         git send-email --to notmuch@notmuchmail.org origin/master
149
150 An alternative is to do this in two steps; first generating patch
151 files (using `git format-patch`), and then sending the patch files to
152 the mailing list (using `git send-email` or a mail client):
153
154         git format-patch origin/master
155         git send-email --to notmuch@notmuchmail.org *.patch
156
157 Either way, using `git send-email` to actually send the patches is
158 recommended. It may be distributed separately from git, typically in a
159 package named `git-email`.
160
161 ## Write a cover letter
162
163 If you are submitting a non-trivial set of patches, or if there's any
164 extra information you want to share that is not really part of the
165 commit messages, it is advisable to write a cover letter to give an
166 overview of your work. See the
167 [Notmuch mailing list archives](https://nmbug.notmuchmail.org/nmweb/)
168 for examples. Use the `--cover-letter` option of `git format-patch`,
169 or `--compose` option of `git send-email`.
170
171 ## Tag your patches in nmbug
172
173 When you're developing an email tool, all the problems start looking
174 like email. This applies to patch and bug tracking as well. The
175 Notmuch project uses [nmbug](https://notmuchmail.org/nmbug/) for
176 tracking. The Notmuch developers will tag your patches too, making
177 them show up in the
178 [nmbug status page](https://nmbug.notmuchmail.org/status/), but requesting
179 access and tagging your patches yourself will be helpful in the long
180 run.
181
182 ## Address review comments, participate in discussion
183
184 Each change to Notmuch must be peer reviewed before it is accepted,
185 usually by one or two developers, depending on the impact of the
186 changes. You are expected to follow up on the review comments you
187 receive, either by discussing the comments and the code, or modifying
188 your patches. Again, see the [Notmuch mailing list
189 archives](https://nmbug.notmuchmail.org/nmweb) for examples.
190
191 ## Send another round addressing review comments
192
193 If your patches need to be changed based on review (they usually do),
194 you need to make the changes and re-submit. `git rebase -i` is your
195 friend in updating your series. Also note that the upstream master may
196 have changed; be sure to rebase your updated changes on top of the
197 current master.
198
199 Once you have the updated series ready, send it to the mailing list
200 again. It will be helpful for others to use the `-vN` option of `git
201 format-patch` or `git send-email` to add a version number of the patch
202 series to the subject (replacing vN with v2, v3, etc.) Use a cover
203 letter (or, in the case of a single patch, the notes after a "---" at
204 the end of the commit message) to summarize the main changes since the
205 previous version of the patch series. Also include the message-id
206 reference of the previous version.
207
208 Using the `--in-reply-to` option of `git format-patch` or
209 `git send-email` to send the patch series as a reply to the earlier
210 version is generally discouraged, particularly for large series, but
211 there are no hard rules. Usually the message-id reference to the
212 previous version is sufficient and preferred.
213
214 Tag the old patches obsolete in [nmbug](https://notmuchmail.org/nmbug/)
215 if you have access.
216
217 ## Review other people's work
218
219 You scratch my back and I'll scratch yours. It will be easier to get
220 people to review your patches if you review theirs.
221
222 ## Report bugs
223
224 Send bug reports to the Notmuch mailing list. Preferably prefix the
225 subject line with "BUG:" or similar. Tag the message as a bug in
226 [nmbug](https://notmuchmail.org/nmbug/).
227
228 Even better, send a patch adding a "known broken" test to the test suite
229 highlighting the issue.
230
231 ## Update the Notmuch website
232
233 Update the Notmuch website, especially if you've landed a commit that
234 changes or obsoletes information on the site. It's a wiki; see the
235 [[instructions on how to edit the wiki|wikiwriteaccess]].
236
237 ## Join the Notmuch IRC channel
238
239 Patch review happens on the Notmuch mailing list, but there is plenty of
240 discussion going on in the libera #notmuch IRC channel. See
241 [libera.chat/guides/connect](https://libera.chat/guides/connect)
242 for information how to get there.