[PATCH] Add commit message guidelines to developer policy

Renato Golin renato.golin at linaro.org
Sun Mar 15 13:33:33 PDT 2015

Changing the attribution section to not duplicate information. Following last round of consensus on the mailing list.



Index: docs/DeveloperPolicy.rst
--- docs/DeveloperPolicy.rst
+++ docs/DeveloperPolicy.rst
@@ -275,6 +275,57 @@
 progress. The developer is welcome to re-commit the change after the problem has
 been fixed.
+.. _commit messages:
+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`.
+* When the changes are restricted to a specific part of the code, say a
+  back-end or optimization pass, it is customary to add a tag to the
+  beginning of the line in square brackets, for example, "[SCEV] ..."
+  or "[OpenMP] ...". This helps email filters or searches for post-commit
+  reviews.
+* 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
@@ -425,8 +476,9 @@
 by J. Random Hacker" (this is noisy and distracting). In practice, the revision
 control system keeps a perfect history of who changed what, and the CREDITS.txt
 file describes higher-level contributions. If you commit a patch for someone
-else, please say "patch contributed by J. Random Hacker!" in the commit
-message. Overall, please do not add contributor names to the source code.
+else, please follow the attribution of changes in the simple manner as outlined
+by the `commit messages`_ section. Overall, please do not add contributor names
+to the source code.
 Also, don't commit patches authored by others unless they have submitted the
 patch to the project or you have been authorized to submit them on their behalf

-------------- next part --------------
A non-text attachment was scrubbed...
Name: D8197.22003.patch
Type: text/x-patch
Size: 3441 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20150315/147a8fc5/attachment.bin>

More information about the cfe-commits mailing list