# HG changeset patch
# User Frederic Bastien <nouiz@nouiz.org>
# Date 1286905075 14400
# Node ID 075a0f1c1ffcf6459b9574704bad723899aae39d
# Parent  d6726417cf5753183665e1b873a64c0cdff26e48
added to the web page the commit message recommendation.

diff -r d6726417cf57 -r 075a0f1c1ffc doc/v2_planning/API_coding_style.txt
--- a/doc/v2_planning/API_coding_style.txt	Sun Oct 10 14:51:02 2010 -0400
+++ b/doc/v2_planning/API_coding_style.txt	Tue Oct 12 13:37:55 2010 -0400
@@ -655,6 +655,44 @@
 
 .. _Wiki page: http://www.iro.umontreal.ca/~lisa/twiki/bin/view.cgi/Divers/VimPythonRecommendations
 
+Commit message
+==============
+
+    * A one line summary. Try to keep it short, and provide the information
+      that seems most useful to other developers: in particular the goal of
+      a change is more useful than its description (which is always
+      available through the changeset patch log). E.g. say "Improved stability
+      of cost computation" rather than "Replaced log(exp(a) + exp(b)) by
+      a * log(1 + exp(b -a)) in cost computation".
+    * If needed a blank line followed by a more detailed summary
+    * Make a commit for each logical modification
+        * This makes reviews easier to do
+        * This makes debugging easier as we can more easily pinpoint errors in 
+	  commits with hg bisect
+    * NEVER commit reformatting with functionality changes
+    * Review your change before commiting
+        * "hg diff <files>..." to see the diff you have done
+        * "hg record" allows you to select which changes to a file should be
+          committed. To enable it, put into the file ~/.hgrc:
+
+          .. code-block:: bash
+
+              [extensions]
+              hgext.record=
+
+        * hg record / diff force you to review your code, never commit without
+          running one of these two commands first
+    * Write detailed commit messages in the past tense, not present tense.
+        * Good: "Fixed Unicode bug in RSS API."
+        * Bad: "Fixes Unicode bug in RSS API."
+        * Bad: "Fixing Unicode bug in RSS API."
+    * Separate bug fixes from feature changes.
+    * If fix a ticket, make the message start with "Fixed #abc"
+        * Can make a system to change the ticket?
+    * If reference a ticket, make the message start with "Refs #abc"
+        * Can make a system to put a comment to the ticket?
+
+
 TODO
 ====