From: Tomi Ollila Date: Tue, 8 Jan 2013 00:06:43 +0000 (+0200) Subject: ESC-q:d paragraphs (fill-paragraph), with human intervention X-Git-Url: https://git.cworth.org/git?p=obsolete%2Fnotmuch-wiki;a=commitdiff_plain;h=b5e9624007ec009dd119473d9c956572fa7cc67e ESC-q:d paragraphs (fill-paragraph), with human intervention --- diff --git a/contributing.mdwn b/contributing.mdwn index 90ea9d2..98dd629 100644 --- a/contributing.mdwn +++ b/contributing.mdwn @@ -1,14 +1,15 @@ [[!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]] @@ -25,9 +26,9 @@ 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: +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 @@ -35,12 +36,13 @@ but a typical workflow might start with: 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 @@ -52,22 +54,24 @@ extra review round. ## 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 -[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:", etc. depending on which part of Notmuch the commit is changing. See `git log` @@ -75,9 +79,9 @@ 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 "---". +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 @@ -100,11 +104,12 @@ 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 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 @@ -114,90 +119,96 @@ If you make user visible changes, you should add an entry 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 -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 -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 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 -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 -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 -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 -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 -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 -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. 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