[PATCH] Add commit message guidelines to developer policy
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.
@@ -275,6 +275,57 @@
progress. The developer is welcome to re-commit the change after the problem has
+.. _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
+* 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
+* 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...
Size: 3441 bytes
Desc: not available
More information about the cfe-commits