This is your friendly guide to contributing to Notmuch. In a nutshell, the
Notmuch project maintains fairly high standards for code, review, tests, and
documentation. It may seem a bit intimidating at first, and you may find it
This is your friendly guide to contributing to Notmuch. In a nutshell, the
Notmuch project maintains fairly high standards for code, review, tests, and
documentation. It may seem a bit intimidating at first, and you may find it
series according to all the details described below at first. Instead, it may
save everyone's time to introduce the idea using draft or work-in-progress
patches, and get the design right from the beginning. Add a cover letter
series according to all the details described below at first. Instead, it may
save everyone's time to introduce the idea using draft or work-in-progress
patches, and get the design right from the beginning. Add a cover letter
## Split your commits in logical chunks
Each commit should contain one logical change only. The code should build and
## Split your commits in logical chunks
Each commit should contain one logical change only. The code should build and
-work after each commit. Changes to lib, cli, emacs, tests, man pages, or news
+the tests should pass after each commit. Changes to lib, cli, emacs, tests,
+man pages, or news
are usually best kept separate. Also separate cleanups from functional
changes. See the Notmuch source history (`git log`) for examples.
are usually best kept separate. Also separate cleanups from functional
changes. See the Notmuch source history (`git log`) for examples.
-highlighting the issue first, and fixing the the bug after that. This makes it
+highlighting the issue in a first patch, and then fix the bug (and remove
+the known broken mark on the test) in the next patch in the series. This
+makes it
easy to confirm your changes actually fix the issue. Some people use this
approach also for adding new features.
easy to confirm your changes actually fix the issue. Some people use this
approach also for adding new features.
[`NEWS`](http://git.notmuchmail.org/git/notmuch/blob/HEAD:/NEWS) file.
## Subscribe to the Notmuch mailing list
[`NEWS`](http://git.notmuchmail.org/git/notmuch/blob/HEAD:/NEWS) file.
## Subscribe to the Notmuch mailing list
the Notmuch mailing list. The simplest way is to use `git send-email` to send
the patches directly from your repository:
the Notmuch mailing list. The simplest way is to use `git send-email` to send
the patches directly from your repository:
An alternative is to do this in two steps; first generating patch files (using
`git format-patch`), and then sending the patch files to the mailing list (using
`git send-email` or a mail client):
An alternative is to do this in two steps; first generating patch files (using
`git format-patch`), and then sending the patch files to the mailing list (using
`git send-email` or a mail client):
git send-email --to notmuch@notmuchmail.org *.patch
Either way, using `git send-email` to actually send the patches is
git send-email --to notmuch@notmuchmail.org *.patch
Either way, using `git send-email` to actually send the patches is
usually do), you need to make the changes and re-submit. `git rebase -i` is your
friend in updating your series. Also note that the upstream master may have
changed; be sure to rebase your updated changes on top of the current master.
Once you have the updated series ready, send it to the mailing list again. It
will be helpful for others to use the `--subject-prefix="PATCH vN"` option of
usually do), you need to make the changes and re-submit. `git rebase -i` is your
friend in updating your series. Also note that the upstream master may have
changed; be sure to rebase your updated changes on top of the current master.
Once you have the updated series ready, send it to the mailing list again. It
will be helpful for others to use the `--subject-prefix="PATCH vN"` option of
(replacing vN with v2, v3, etc.) Use a cover letter (or, in the case of a single
patch, the notes after a "---" at the end of the commit message) to summarize
the main changes since the previous version of the patch series. Also include
(replacing vN with v2, v3, etc.) Use a cover letter (or, in the case of a single
patch, the notes after a "---" at the end of the commit message) to summarize
the main changes since the previous version of the patch series. Also include