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

[notmuch-wiki] / patchformatting.mdwn

diff --git a/patchformatting.mdwn b/patchformatting.mdwn
index 6ff103a2421df3010240c1d492024c66cb884fcc..8f3203159ba0800f40b68b20f9b01e758c065ad5 100644 (file)
--- a/patchformatting.mdwn
+++ b/patchformatting.mdwn
@@ -10,7 +10,7 @@ you should check the following:
 
 2. Read mailing list (archives) and follow the discussions on the patches sent.
 
-3. Get familiar with coding conventions used (in any particular project).
+3. Get familiar with coding conventions used.
 
 This way you get some insight of the look and feel of the patches sent,
 both the way code should be written, how to write commit log messages
@@ -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)
@@ -119,6 +154,10 @@ actual patch sending to the mailing list.
 
 ### Sending one patch using compatible (emacs) email client.
 
+Sometimes using git-send-email is not possible; It is not installed by
+default and you don't have privileges to install it or you are not
+able to compile it as it has more build-time requirements as git itself.
+
 One alternative way to send your patches is to use, for example, the
 emacs mail client you've already used to send mails to mailing list.
 In this case you have to be very careful to keep the patch contents