git.cworth.org Git - obsolete/notmuch-wiki/blob - contributing.mdwn

   1 [[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
   2 # Contributing to Notmuch
   3
   4 __This page is a work in progress__
   5
   6 This is your friendly guide to contributing to Notmuch. In a nutshell, the
   7 Notmuch project maintains fairly high standards for code, review, tests, and
   8 documentation. It may seem a bit intimidating at first, and you may find it
   9 difficult to get your first contributions accepted, but once you get the hang of
  10 it, it'll be fun. This page should help you get there. DON'T PANIC.
  11
  12 The headlines below act as a checklist. Not all of them apply in all situations;
  13 use common sense.
  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 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 Notmuch git
  31 master. There are plenty of ways to work in git, and this is not your git guide,
  32 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 the patch
  41 series according to all the details described below at first. Instead, it may
  42 save everyone's time to introduce the idea using draft or work-in-progress
  43 patches, and get the design right from the beginning. Add a cover letter
  44 explaining what you want to achieve. You may prefix the subjects of such patches
  45 with "RFC" or "DRAFT" if you like.
  46
  47 ## Pay attention to the Notmuch coding style
  48
  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
  53 extra review round.
  54
  55 ## Split your commits in logical chunks
  56
  57 Each commit should contain one logical change only. The code should build and
  58 the tests should pass after each commit. Changes to lib, cli, emacs, tests,
  59 man pages, or news
  60 are usually best kept separate. Also separate cleanups from functional
  61 changes. See the Notmuch source history (`git log`) for examples.
  62
  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.
  65
  66 ## Write meaningful commit messages
  67
  68 [Quoting Carl](http://article.gmane.org/gmane.mail.notmuch.general/504), "The
  69 single line summary is good about saying what the commit does, but I always want
  70 to see at least one sentence about the why as well."
  71
  72 See also [Pro Git](http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines) on commit guidelines, including commit messages.
  73
  74 It is customary to prefix the subject line with "lib:", "cli:", "emacs:",
  75 etc. depending on which part of Notmuch the commit is changing. See `git log`
  76 for examples.
  77
  78 Wrap the lines to about 72 characters.
  79
  80 If you want to share notes that shall not become part of the commit message when
  81 applied to the upstream Notmuch repository, add the notes at the end, after a
  82 line containing "---".
  83
  84 ## Update the test suite
  85
  86 Notmuch has a test suite with fairly good coverage. At the very least, `make
  87 test` must pass after your changes. Therefore you must amend the tests if you
  88 make functional changes that have existing test coverage. Preferrably, you
  89 should add new tests for any new functionality, and it helps in getting your
  90 changes accepted.
  91
  92 If you're fixing a bug, it is recommended to add a "known broken" test
  93 highlighting the issue in a first patch, and then fix the bug (and remove
  94 the known broken mark on the test) in the next patch in the series. This
  95 makes it
  96 easy to confirm your changes actually fix the issue. Some people use this
  97 approach also for adding new features.
  98
  99 See
 100 [`test/README`](http://git.notmuchmail.org/git/notmuch/blob/HEAD:/test/README)
 101 in the Notmuch source for further information.
 102
 103 ## Update the documentation
 104
 105 If you modify or add new features to the Notmuch command-line tools, you should
 106 update the manual pages under the `man` directory of the Notmuch source.
 107
 108 If you modify or add new features to the Notmuch Emacs UI, you should update the
 109 Emacs documentation.
 110
 111 ## Update NEWS
 112
 113 If you make user visible changes, you should add an entry to the
 114 [`NEWS`](http://git.notmuchmail.org/git/notmuch/blob/HEAD:/NEWS) file.
 115
 116 ## Subscribe to the Notmuch mailing list
 117
 118 While strictly not required, it is advisable to subscribe to the
 119 [Notmuch mailing list](http://notmuchmail.org/mailman/listinfo/notmuch) before
 120 submitting patches.
 121
 122 ## Send your patches to the mailing list
 123
 124 Changes to Notmuch are contributed as
 125 [emailed patches](http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Public-Large-Project). Once
 126 you have your changes ready in your local repository, you need to send them to
 127 the Notmuch mailing list. The simplest way is to use `git send-email` to send
 128 the patches directly from your repository:
 129
 130         git send-email --to notmuch@notmuchmail.org origin/master
 131
 132 An alternative is to do this in two steps; first generating patch files (using
 133 `git format-patch`), and then sending the patch files to the mailing list (using
 134 `git send-email` or a mail client):
 135
 136         git format-patch origin/master
 137         git send-email --to notmuch@notmuchmail.org *.patch
 138
 139 Either way, using `git send-email` to actually send the patches is
 140 recommended. It may be distributed separately from git, typically in a package
 141 named `git-email`.
 142
 143 ## Write a cover letter
 144
 145 If you are submitting a non-trivial set of patches, or if there's any extra
 146 information you want to share that is not really part of the commit messages, it
 147 is advisable to write a cover letter to give an overview of your work. See the
 148 [Notmuch mailing list archives](http://notmuchmail.org/pipermail/notmuch/) for
 149 examples. Use the `--cover-letter` option of `git format-patch`, or `--compose`
 150 option of `git send-email`.
 151
 152 ## Tag your patches in nmbug
 153
 154 When you're developing an email tool, all the problems start looking like
 155 email. This applies to patch and bug tracking as well. The Notmuch project uses
 156 [nmbug](http://notmuchmail.org/nmbug/) for tracking. The Notmuch developers will
 157 tag your patches too, making them show up in the
 158 [nmbug status page](http://nmbug.tethera.net/status/), but requesting access and
 159 tagging your patches yourself will be helpful in the long run.
 160
 161 ## Address review comments, participate in discussion
 162
 163 Each change to Notmuch must be peer reviewed before it is accepted, usually by
 164 one or two developers, depending on the impact of the changes. You are expected
 165 to follow up on the review comments you receive, either by discussing the
 166 comments and the code, or modifying your patches. Again, see the
 167 [Notmuch mailing list archives](http://notmuchmail.org/pipermail/notmuch/) for
 168 examples.
 169
 170 ## Send another round addressing review comments
 171
 172 If your patches need to be changed based on review (they
 173 usually do), you need to make the changes and re-submit. `git rebase -i` is your
 174 friend in updating your series. Also note that the upstream master may have
 175 changed; be sure to rebase your updated changes on top of the current master.
 176
 177 Once you have the updated series ready, send it to the mailing list again. It
 178 will be helpful for others to use the `--subject-prefix="PATCH vN"` option of
 179 `git format-patch` or `git send-email` to add a version number of the patch
 180 series to the subject
 181 (replacing vN with v2, v3, etc.) Use a cover letter (or, in the case of a single
 182 patch, the notes after a "---" at the end of the commit message) to summarize
 183 the main changes since the previous version of the patch series. Also include
 184 the message-id reference of the previous version.
 185
 186 Using the `--in-reply-to` option of `git format-patch` or `git send-email` to
 187 send the patch series as a reply to the earlier version is generally
 188 discouraged, particularly for large series, but there are no hard rules. Usually
 189 the message-id reference to the previous version is sufficient and preferred.
 190
 191 Tag the old patches obsolete in [nmbug](http://notmuchmail.org/nmbug/) if you
 192 have access.
 193
 194 ## Review other people's work
 195
 196 You scratch my back and I'll scratch yours. It will be easier to get people to
 197 review your patches if you review theirs.
 198
 199 ## Report bugs
 200
 201 Send bug reports to the Notmuch mailing list. Preferrably prefix the subject
 202 line with "BUG:" or similar. Tag the message as a bug in
 203 [nmbug](http://notmuchmail.org/nmbug/).
 204
 205 Even better, send a patch adding a "known broken" test to the test suite
 206 highlighting the issue.
 207
 208 ## Join the Notmuch IRC channel
 209
 210 Patch review happens on the Notmuch mailing list, but there is plenty of
 211 discussion going on in the #notmuch IRC channel.