git.notmuchmail.org Git - notmuch-wiki/blob - 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 ## Update NEWS
 116
 117 If you make user visible changes, you should add an entry to the
 118 [`NEWS`](https://git.notmuchmail.org/git/notmuch/blob/HEAD:/NEWS) file.
 119
 120 ## Update command-line completion
 121
 122 If you modify or add new features to the Notmuch command-line tools, it
 123 would be a nice bonus if you also updated the Notmuch command-line
 124 completion scripts under the `completion` directory of the Notmuch
 125 source. Not required, but nice to have, and definitely can be done
 126 afterwards.
 127
 128 ## Subscribe to the Notmuch mailing list
 129
 130 While strictly not required, it is advisable to subscribe to the
 131 [Notmuch mailing list](https://nmbug.notmuchmail.org/list/)
 132 before submitting patches.
 133
 134 ## Send your patches to the mailing list
 135
 136 Changes to Notmuch are contributed as [emailed
 137 patches](http://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#Public-Project-over-Email).
 138 Once you have your changes ready in your local repository, you need to
 139 send them to the Notmuch mailing list. The simplest way is to use `git
 140 send-email` to send the patches directly from your repository:
 141
 142         git send-email --to notmuch@notmuchmail.org origin/master
 143
 144 An alternative is to do this in two steps; first generating patch
 145 files (using `git format-patch`), and then sending the patch files to
 146 the mailing list (using `git send-email` or a mail client):
 147
 148         git format-patch origin/master
 149         git send-email --to notmuch@notmuchmail.org *.patch
 150
 151 Either way, using `git send-email` to actually send the patches is
 152 recommended. It may be distributed separately from git, typically in a
 153 package named `git-email`.
 154
 155 ## Write a cover letter
 156
 157 If you are submitting a non-trivial set of patches, or if there's any
 158 extra information you want to share that is not really part of the
 159 commit messages, it is advisable to write a cover letter to give an
 160 overview of your work. See the
 161 [Notmuch mailing list archives](https://nmbug.notmuchmail.org/nmweb/)
 162 for examples. Use the `--cover-letter` option of `git format-patch`,
 163 or `--compose` option of `git send-email`.
 164
 165 ## Tag your patches in nmbug
 166
 167 When you're developing an email tool, all the problems start looking
 168 like email. This applies to patch and bug tracking as well. The
 169 Notmuch project uses [nmbug](https://notmuchmail.org/nmbug/) for
 170 tracking. The Notmuch developers will tag your patches too, making
 171 them show up in the
 172 [nmbug status page](https://nmbug.notmuchmail.org/status/), but requesting
 173 access and tagging your patches yourself will be helpful in the long
 174 run.
 175
 176 ## Address review comments, participate in discussion
 177
 178 Each change to Notmuch must be peer reviewed before it is accepted,
 179 usually by one or two developers, depending on the impact of the
 180 changes. You are expected to follow up on the review comments you
 181 receive, either by discussing the comments and the code, or modifying
 182 your patches. Again, see the [Notmuch mailing list
 183 archives](https://nmbug.notmuchmail.org/nmweb) for examples.
 184
 185 ## Send another round addressing review comments
 186
 187 If your patches need to be changed based on review (they usually do),
 188 you need to make the changes and re-submit. `git rebase -i` is your
 189 friend in updating your series. Also note that the upstream master may
 190 have changed; be sure to rebase your updated changes on top of the
 191 current master.
 192
 193 Once you have the updated series ready, send it to the mailing list
 194 again. It will be helpful for others to use the `-vN` option of `git
 195 format-patch` or `git send-email` to add a version number of the patch
 196 series to the subject (replacing vN with v2, v3, etc.) Use a cover
 197 letter (or, in the case of a single patch, the notes after a "---" at
 198 the end of the commit message) to summarize the main changes since the
 199 previous version of the patch series. Also include the message-id
 200 reference of the previous version.
 201
 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.
 207
 208 Tag the old patches obsolete in [nmbug](https://notmuchmail.org/nmbug/)
 209 if you have access.
 210
 211 ## Review other people's work
 212
 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.
 215
 216 ## Report bugs
 217
 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](https://notmuchmail.org/nmbug/).
 221
 222 Even better, send a patch adding a "known broken" test to the test suite
 223 highlighting the issue.
 224
 225 ## Update the Notmuch website
 226
 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]].
 230
 231 ## Join the Notmuch IRC channel
 232
 233 Patch review happens on the Notmuch mailing list, but there is plenty of
 234 discussion going on in the libera #notmuch IRC channel. See
 235 [libera.chat/guides/connect](https://libera.chat/guides/connect)
 236 for information how to get there.