Update news & manpages to notmuch version 0.16

[obsolete/notmuch-wiki] / contributing.mdwn

diff --git a/contributing.mdwn b/contributing.mdwn
index 90ea9d23fbf30608137ea97262be4b8c06071245..3729a766cbbc9948401b3c149a15d8c6131227aa 100644 (file)
--- a/contributing.mdwn
+++ b/contributing.mdwn
@@ -1,14 +1,15 @@
 [[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
 # Contributing to Notmuch
 
 [[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
 # Contributing to Notmuch
 

-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
-difficult to get your first contributions accepted, but once you get the hang of
-it, it'll be fun. This page should help you get there. DON'T PANIC.
+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 difficult to get your first contributions accepted,
+but once you get the hang of it, it'll be fun. This page should help
+you get there. DON'T PANIC.

 
 

-The headlines below act as a checklist. Not all of them apply in all situations;
-use common sense.
+The headlines below act as a checklist. Not all of them apply in all
+situations; use common sense.

 
 [[!toc levels=2]]
 
 
 [[!toc levels=2]]
 


@@ -17,7 +18,7 @@ use common sense.
 The Notmuch source code is maintained in [git](http://git-scm.com/). Get the
 source code using:
 
 The Notmuch source code is maintained in [git](http://git-scm.com/). Get the
 source code using:
 

-       git clone git://notmuchmail.org/git/notmuch
+        git clone git://notmuchmail.org/git/notmuch

 
 This guide assumes a working knowledge of git. There are plenty of resources
 available on git, such as [Pro Git](http://git-scm.com/book) and the git man
 
 This guide assumes a working knowledge of git. There are plenty of resources
 available on git, such as [Pro Git](http://git-scm.com/book) and the git man


@@ -25,22 +26,23 @@ pages. Please refer to them as necessary.
 
 ## Make your changes
 
 
 ## Make your changes
 

-The changes you submit should almost always be based on the current Notmuch git
-master. There are plenty of ways to work in git, and this is not your git guide,
-but a typical workflow might start with:
+The changes you submit should almost always be based on the current
+Notmuch git master. There are plenty of ways to work in git, and this
+is not your git guide, but a typical workflow might start with:

 
 

-       git fetch origin
-       git checkout -b my-local-branch origin/master
-       # make changes
-       git add ...
-       git commit
+        git fetch origin
+        git checkout -b my-local-branch origin/master
+        # make changes
+        git add ...
+        git commit

 
 

-If you're planning big changes, it may be advisable to __not__ polish the patch
-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
-explaining what you want to achieve. You may prefix the subjects of such patches
-with "RFC" or "DRAFT" if you like.
+If you're planning big changes, it may be advisable to __not__ polish
+the patch 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 explaining what you want to
+achieve. You may prefix the subjects of such patches with "RFC" or
+"DRAFT" if you like.

 
 ## Pay attention to the Notmuch coding style
 
 
 ## Pay attention to the Notmuch coding style
 


@@ -52,38 +54,40 @@ extra review round.
 
 ## Split your commits in logical chunks
 
 
 ## Split your commits in logical chunks
 

-Each commit should contain one logical change only. The code should build and
-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.
+Each commit should contain one logical change only. The code should
+build and 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.

 
 

-For in-depth discussion on the subject, see 
+For in-depth discussion on the subject, see

 [Software Release Practice HOWTO](http://tldp.org/HOWTO/Software-Release-Practice-HOWTO/) by Eric S. Raymond.
 
 ## Write meaningful commit messages
 
 [Software Release Practice HOWTO](http://tldp.org/HOWTO/Software-Release-Practice-HOWTO/) by Eric S. Raymond.
 
 ## Write meaningful commit messages
 

-[Quoting Carl](http://article.gmane.org/gmane.mail.notmuch.general/504), "The
-single line summary is good about saying what the commit does, but I always want
-to see at least one sentence about the why as well."
+[Quoting Carl](http://article.gmane.org/gmane.mail.notmuch.general/504),
+"The single line summary is good about saying what the commit does,
+but I always want to see at least one sentence about the why as well."

 
 

-See also [Pro Git](http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines) on commit guidelines, including commit messages.
+See also
+[Pro Git](http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines)
+on commit guidelines, including commit messages.

 
 It is customary to prefix the subject line with "lib:", "cli:", "emacs:",
 
 It is customary to prefix the subject line with "lib:", "cli:", "emacs:",

-etc. depending on which part of Notmuch the commit is changing. See `git log`
-for examples.
+etc. depending on which part of Notmuch the commit is changing. See
+**`git log`** for examples.

 
 Wrap the lines to about 72 characters.
 
 
 Wrap the lines to about 72 characters.
 

-If you want to share notes that shall not become part of the commit message when
-applied to the upstream Notmuch repository, add the notes at the end, after a
-line containing "---".
+If you want to share notes that shall not become part of the commit
+message when applied to the upstream Notmuch repository, add the notes
+at the end, after a line containing "---".

 
 ## Update the test suite
 
 Notmuch has a test suite with fairly good coverage. At the very least, `make
 test` must pass after your changes. Therefore you must amend the tests if you
 
 ## Update the test suite
 
 Notmuch has a test suite with fairly good coverage. At the very least, `make
 test` must pass after your changes. Therefore you must amend the tests if you

-make functional changes that have existing test coverage. Preferrably, you
+make functional changes that have existing test coverage. Preferably, you

 should add new tests for any new functionality, and it helps in getting your
 changes accepted.
 
 should add new tests for any new functionality, and it helps in getting your
 changes accepted.
 


@@ -100,109 +104,130 @@ in the Notmuch source for further information.
 
 ## Update the documentation
 
 
 ## Update the documentation
 

-If you modify or add new features to the Notmuch command-line tools, you should
-update the manual pages under the `man` directory of the Notmuch source.
+If you modify or add new features to the Notmuch command-line tools,
+you should update the manual pages under the `man` directory of the
+Notmuch source.

 
 

-If you modify or add new features to the Notmuch Emacs UI, you should update the
-Emacs documentation.
+If you modify or add new features to the Notmuch Emacs UI, you should
+update the Emacs documentation.

 
 ## Update NEWS
 
 If you make user visible changes, you should add an entry to the
 [`NEWS`](http://git.notmuchmail.org/git/notmuch/blob/HEAD:/NEWS) file.
 
 
 ## Update NEWS
 
 If you make user visible changes, you should add an entry to the
 [`NEWS`](http://git.notmuchmail.org/git/notmuch/blob/HEAD:/NEWS) file.
 

+## Update command-line completion
+
+If you modify or add new features to the Notmuch command-line tools, it
+would be a nice bonus if you also updated the Notmuch command-line
+completion scripts under the `completion` directory of the Notmuch
+source. Not required, but nice to have, and definitely can be done
+afterwards.
+

 ## Subscribe to the Notmuch mailing list
 
 While strictly not required, it is advisable to subscribe to the
 ## Subscribe to the Notmuch mailing list
 
 While strictly not required, it is advisable to subscribe to the

-[Notmuch mailing list](http://notmuchmail.org/mailman/listinfo/notmuch) before
-submitting patches.
+[Notmuch mailing list](http://notmuchmail.org/mailman/listinfo/notmuch)
+before submitting patches.

 
 ## Send your patches to the mailing list
 
 
 ## Send your patches to the mailing list
 

-Changes to Notmuch are contributed as
-[emailed patches](http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Public-Large-Project). Once
-you have your changes ready in your local repository, you need to send them to
-the Notmuch mailing list. The simplest way is to use `git send-email` to send
-the patches directly from your repository:
+Changes to Notmuch are contributed as [emailed
+patches](http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Public-Large-Project).
+Once you have your changes ready in your local repository, you need to
+send them to the Notmuch mailing list. The simplest way is to use `git
+send-email` to send the patches directly from your repository:

 
 

-       git send-email --to notmuch@notmuchmail.org origin/master
+        git send-email --to notmuch@notmuchmail.org origin/master

 
 

-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 format-patch origin/master
-       git send-email --to notmuch@notmuchmail.org *.patch
+        git format-patch origin/master
+        git send-email --to notmuch@notmuchmail.org *.patch

 
 Either way, using `git send-email` to actually send the patches is
 
 Either way, using `git send-email` to actually send the patches is

-recommended. It may be distributed separately from git, typically in a package
-named `git-email`.
+recommended. It may be distributed separately from git, typically in a
+package named `git-email`.

 
 ## Write a cover letter
 
 
 ## Write a cover letter
 

-If you are submitting a non-trivial set of patches, or if there's any extra
-information you want to share that is not really part of the commit messages, it
-is advisable to write a cover letter to give an overview of your work. See the
-[Notmuch mailing list archives](http://notmuchmail.org/pipermail/notmuch/) for
-examples. Use the `--cover-letter` option of `git format-patch`, or `--compose`
-option of `git send-email`.
+If you are submitting a non-trivial set of patches, or if there's any
+extra information you want to share that is not really part of the
+commit messages, it is advisable to write a cover letter to give an
+overview of your work. See the
+[Notmuch mailing list archives](http://notmuchmail.org/pipermail/notmuch/)
+for examples. Use the `--cover-letter` option of `git format-patch`,
+or `--compose` option of `git send-email`.

 
 ## Tag your patches in nmbug
 
 
 ## Tag your patches in nmbug
 

-When you're developing an email tool, all the problems start looking like
-email. This applies to patch and bug tracking as well. The Notmuch project uses
-[nmbug](http://notmuchmail.org/nmbug/) for tracking. The Notmuch developers will
-tag your patches too, making them show up in the
-[nmbug status page](http://nmbug.tethera.net/status/), but requesting access and
-tagging your patches yourself will be helpful in the long run.
+When you're developing an email tool, all the problems start looking
+like email. This applies to patch and bug tracking as well. The
+Notmuch project uses [nmbug](http://notmuchmail.org/nmbug/) for
+tracking. The Notmuch developers will tag your patches too, making
+them show up in the
+[nmbug status page](http://nmbug.tethera.net/status/), but requesting
+access and tagging your patches yourself will be helpful in the long
+run.

 
 ## Address review comments, participate in discussion
 
 
 ## Address review comments, participate in discussion
 

-Each change to Notmuch must be peer reviewed before it is accepted, usually by
-one or two developers, depending on the impact of the changes. You are expected
-to follow up on the review comments you receive, either by discussing the
-comments and the code, or modifying your patches. Again, see the
-[Notmuch mailing list archives](http://notmuchmail.org/pipermail/notmuch/) for
-examples.
+Each change to Notmuch must be peer reviewed before it is accepted,
+usually by one or two developers, depending on the impact of the
+changes. You are expected to follow up on the review comments you
+receive, either by discussing the comments and the code, or modifying
+your patches. Again, see the [Notmuch mailing list
+archives](http://notmuchmail.org/pipermail/notmuch/) for examples.

 
 ## Send another round addressing review comments
 
 
 ## Send another round addressing review comments
 

-If your patches need to be changed based on review (they
-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
-`git format-patch` or `git send-email` to add a version number of the patch
-series to the subject
-(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
-the message-id reference of the previous version.
-
-Using the `--in-reply-to` option of `git format-patch` or `git send-email` to
-send the patch series as a reply to the earlier version is generally
-discouraged, particularly for large series, but there are no hard rules. Usually
-the message-id reference to the previous version is sufficient and preferred.
-
-Tag the old patches obsolete in [nmbug](http://notmuchmail.org/nmbug/) if you
-have access.
+If your patches need to be changed based on review (they 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 `git format-patch` or
+`git send-email` to add a version number of the patch series to the
+subject (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 the message-id reference of
+the previous version.
+
+Using the `--in-reply-to` option of `git format-patch` or
+`git send-email` to send the patch series as a reply to the earlier
+version is generally discouraged, particularly for large series, but
+there are no hard rules. Usually the message-id reference to the
+previous version is sufficient and preferred.
+
+Tag the old patches obsolete in [nmbug](http://notmuchmail.org/nmbug/)
+if you have access.

 
 ## Review other people's work
 
 
 ## Review other people's work
 

-You scratch my back and I'll scratch yours. It will be easier to get people to
-review your patches if you review theirs.
+You scratch my back and I'll scratch yours. It will be easier to get
+people to review your patches if you review theirs.

 
 ## Report bugs
 
 
 ## Report bugs
 

-Send bug reports to the Notmuch mailing list. Preferrably prefix the subject
-line with "BUG:" or similar. Tag the message as a bug in
+Send bug reports to the Notmuch mailing list. Preferably prefix the
+subject line with "BUG:" or similar. Tag the message as a bug in

 [nmbug](http://notmuchmail.org/nmbug/).
 
 Even better, send a patch adding a "known broken" test to the test suite
 highlighting the issue.
 
 [nmbug](http://notmuchmail.org/nmbug/).
 
 Even better, send a patch adding a "known broken" test to the test suite
 highlighting the issue.
 

+## Update the Notmuch website
+
+Update the Notmuch website, especially if you've landed a commit that
+changes or obsoletes information on the site. It's a wiki; see the
+[[instructions on how to edit the wiki|wikiwriteaccess]].
+

 ## Join the Notmuch IRC channel
 
 Patch review happens on the Notmuch mailing list, but there is plenty of
 ## Join the Notmuch IRC channel
 
 Patch review happens on the Notmuch mailing list, but there is plenty of