From ac830a3f76ad34c5e43f97fa01ac4be2cf69e8db Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Mon, 7 Jan 2013 23:39:04 +0200 Subject: [PATCH] draft: contributing.mdwn Add a draft guide on how to contribute to notmuch that is hopefully a little bit less intimidating than what patchformatting.mdwn has become. --- contributing.mdwn | 207 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 207 insertions(+) create mode 100644 contributing.mdwn diff --git a/contributing.mdwn b/contributing.mdwn new file mode 100644 index 0000000..316bcea --- /dev/null +++ b/contributing.mdwn @@ -0,0 +1,207 @@ +[[!img notmuch-logo.png alt="Notmuch logo" class="left"]] +# Contributing to Notmuch + +__This page is a work in progress__ + +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. + +[[!toc levels=2]] + +## Obtain the Notmuch source code + +The Notmuch source code is maintained in [git](http://git-scm.com/). Get the +source code using: + + 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 +pages. Please refer to them as necessary. + +## 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: + + 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 +exlaining 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 + +The Notmuch code base follows a fairly uniform coding style. See the existing +code around your changes, and read +[`devel/STYLE`](http://git.notmuchmail.org/git/notmuch/blob/HEAD:/devel/STYLE) +in the Notmuch source. It's not difficult to get it right, and may save you an +extra review round. + +## 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 +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 +[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." + +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:", +etc. depending on which part of Notmuch the commit is changing. See `git log` +for examples. + +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 "---". + +## 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 +should add new tests for any new functionality, and it helps in getting your +changes accepted. + +If you're fixing a bug, it is recommended to add a "known broken" test +highlighting the issue first, and fixing the the bug after that. This makes it +easy to confirm your changes actually fix the issue. Some people use this +approach also for adding new features. + +See +[`test/README`](http://git.notmuchmail.org/git/notmuch/blob/HEAD:/test/README) +in the Notmuch source for further information. + +## 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 Emacs UI, you should update the +Emacs documentation. + +## Update NEWS + +If you make user visible changes, you should update the +[`NEWS`](http://git.notmuchmail.org/git/notmuch/blob/HEAD:/NEWS) file. + +## 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. + +## 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: + + git send-email --to notmuch@notmuchmail.org origin + +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 + git send-email --to notmuch@notmuchmail.org *.patch + +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`. + +## 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`. + +## 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. + +## 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. + +## Send another round addressing review comments + +If your patches need to be changed based on review (for large patch series 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` 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 + +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 + +Send bug reports to the Notmuch mailing list. Preferrably 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. + +## Join the Notmuch IRC channel + +Patch review happens on the Notmuch mailing list, but there is plenty of +discussion going on in the #notmuch IRC channel. -- 2.43.0