patchformatting.mdwn: added cworth's statement re commit msg body

[notmuch-wiki] / patchformatting.mdwn

diff --git a/patchformatting.mdwn b/patchformatting.mdwn
index cf5bf813c082337c0e3f2799b3f12f1588ef184a..8f3203159ba0800f40b68b20f9b01e758c065ad5 100644 (file)
--- a/patchformatting.mdwn
+++ b/patchformatting.mdwn
@@ -33,6 +33,31 @@ Enter your commit message in following format:
 The 65-character (limit) seems to be common among many projects so
 that is good guideline to follow here too.
 
+Regarding the commit message body contents, Carl [has stated](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.
+
+### Activating default pre-commit hook
+
+Git provides a default pre-commit hook which, when activated, checks
+(at least) for whitespace errors (trailing whitespace and space before
+tab). It is better to notice this kind of "errors" early than have
+patch reviewers to mention about those.
+
+The hook, when activated, is named as .git/hooks/pre-commit and it
+has execute permissions set on. By default, when git tree is cloned
+your hooks dir may have default, inactive pre-commit hook available
+as:
+
+1. .git/hooks/pre-commit  without execute permission set
+
+2. .git/hooks/pre-commit.sample  usually with execute permission set
+
+In case of 2, enter `cp .git/hooks/pre-commit.sample .git/hooks/pre-commit`.
+And, now enter `chmod a+x .git/hooks/pre-commit` in case it does not
+have execute permission set.
+
 ## Remember: one patch per email
 
 Every patch should (must!) contain only one bugfix or new feature.
@@ -41,6 +66,16 @@ Eric S. Raymond has written good
 [Software Release Practice HOWTO](http://tldp.org/HOWTO/Software-Release-Practice-HOWTO/).
 Check what he has to say about this issue. 
 
+### Test Suite Enhancements
+
+New features as well as bug fixes should typically come with test suite
+enhancements.  The test suite changes should be done first (tagged as *expected
+to fail*), and the feature implementation or bug fix should come second
+(removing the *expected to fail* tag).  This way, the test suite specifies the
+behavior you're trying to implement, be it a new feature or a bug fix.  By
+defining beforehand exactly what you expect to happen, everyone can confirm
+that your patch achieves what it is meant it to.
+
 ## Prepare patches for e-mail submission
 
 If you've made just one commit (containing just one bugfix or new feature)