[Python-checkins] devguide: Explain the common formatting of commit messages.

[brett.cannon]

brett.cannon pushed ee55d8156c66 to devguide:

http://hg.python.org/devguide/rev/ee55d8156c66
changeset:   209:ee55d8156c66
tag:         tip
user:        Brett Cannon <brett at python.org>
date:        Wed Jan 26 13:05:30 2011 -0800
summary:
  Explain the common formatting of commit messages.

files:
  committing.rst

diff --git a/committing.rst b/committing.rst
--- a/committing.rst
+++ b/committing.rst
@@ -3,6 +3,36 @@
 Committing Patches
 ==================
 
+Commit Messages
+---------------
+Every commit has a commit message to document why a change was made and to
+communicate that reason to other core developers. Python core developers have
+developed a standard way of formatting commit messages that everyone is
+expected to follow.
+
+Here is an example commit message::
+
+    Fixed the spam module to be more spammy.
+
+    The spam module sporadically came up short on spam. This change raises the
+    amount of spam in the module by making it more spammy.
+
+    Fixes issue #42. Thanks to Monty Python for the patch.
+
+The first line is meant to be a dense, to-the-point explanation of what the
+purpose of the commit is. If this is not enough detail for a commit, a new
+paragraph(s) can be added to explain in proper depth what has happened (detail
+should be good enough that a core developer reading the commit message
+understands the justification for the change).
+
+Finally, a separate line is
+provided if the commit is related to an issue (e.g., fixes a bug or applies a
+patch) and/or someone did a review of the code. If the issue is closing a bug,
+then typically "Fixes issue #NNNN" is typically used. If a patch from an issue
+is applied, then "Closes issue #NNNN" is typically used along with a "thank
+you" note to the patch creator. If someone did a patch review they also get
+thanked.
+
 
 Handling Other's Code
 ---------------------

--
Repository URL: http://hg.python.org/devguide