[PATCH] Add commit message guidelines to developer policy

[Renato Golin]

Changing in response to comments.


REPOSITORY
  rL LLVM

http://reviews.llvm.org/D8197

Files:
  docs/DeveloperPolicy.rst

Index: docs/DeveloperPolicy.rst
===================================================================
--- docs/DeveloperPolicy.rst
+++ docs/DeveloperPolicy.rst
@@ -275,6 +275,49 @@
 progress. The developer is welcome to re-commit the change after the problem has
 been fixed.
 
+Commit messages
+---------------
+
+Although we don't enforce the format of commit messages, there are general
+guidelines that will help review, search in logs, email formatting and so on.
+Mostly, the rules that apply are similar to other projects.
+
+More importantly, the contents of the message have to be carefully written to
+convey the rationale of the change without delving too much in detail. It
+also should avoid being vague or overly specific. For example, "bits were not
+set right" will leave the reviewer wondering about which bits, and why they
+weren't right, while "Correct add instruction bits in TargetInfo" convey almost
+all there is to the change.
+
+Below are some guidelines about the format of the message itself:
+
+* Separate the commit message into title, body and, if you're not the original
+  author, a "Patch by" line (see below).
+
+* The title should be concise. All commits are emailed to the list, and the
+  first line is used as the subject, so long titles are really frowned
+  upon. They also look a lot better in a `git log`.
+
+* The body, if it exists, should be separated from the title by an empty line.
+
+* The body should have as many paragraphs as necessary, but not more than that.
+  Meaning you should be concise, but explanatory, including a complete
+  reasoning, but leaving examples, code snippets and gory details to bug
+  comments, web review or the mailing list.
+
+* `Attribution of Changes`_ should be in a separate line, after the end of
+  the body, as simple as "Patch by John Doe.". This is how we officially
+  handle attribution, and there are automated processes that rely on this
+  format.
+
+* Text formatting and spelling should follow the same rules as documentation
+  and in-code comments, ex. capitalization, full stop, etc.
+
+For minor violations of this policy, the community normally favors reminding
+the contributor of this policy over reverting. Minor corrections and omissions
+can be handled by sending a reply to the commits mailing list.
+
+
 Obtaining Commit Access
 -----------------------

EMAIL PREFERENCES
  http://reviews.llvm.org/settings/panel/emailpreferences/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: D8197.21912.patch
Type: text/x-patch
Size: 2362 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20150313/f487e51c/attachment.bin>