<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Sun, Mar 15, 2015 at 2:15 PM, Renato Golin <span dir="ltr"><<a href="mailto:renato.golin@linaro.org" target="_blank">renato.golin@linaro.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Author: rengolin<br>
Date: Sun Mar 15 16:15:48 2015<br>
New Revision: 232334<br>
<br>
URL: <a href="http://llvm.org/viewvc/llvm-project?rev=232334&view=rev" target="_blank">http://llvm.org/viewvc/llvm-project?rev=232334&view=rev</a><br>
Log:<br>
Adding commit msg guidelines to dev policy<br>
<br>
After much bike shed discussions, we seem to agree to a few loose<br>
but relevant guidelines on how to prepare a commit message. It also<br>
points the attribution section to the new commit messages section<br>
to deduplicate information.<br>
<br>
Modified:<br>
llvm/trunk/docs/DeveloperPolicy.rst<br>
<br>
Modified: llvm/trunk/docs/DeveloperPolicy.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/DeveloperPolicy.rst?rev=232334&r1=232333&r2=232334&view=diff" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/DeveloperPolicy.rst?rev=232334&r1=232333&r2=232334&view=diff</a><br>
==============================================================================<br>
--- llvm/trunk/docs/DeveloperPolicy.rst (original)<br>
+++ llvm/trunk/docs/DeveloperPolicy.rst Sun Mar 15 16:15:48 2015<br>
@@ -275,6 +275,59 @@ reverted. This is necessary when the cha<br>
progress. The developer is welcome to re-commit the change after the problem has<br>
been fixed.<br>
<br>
+.. _commit messages:<br>
+<br>
+Commit messages<br>
+---------------<br>
+<br>
+Although we don't enforce the format of commit messages, we prefer that<br>
+you follow these guidelines to help review, search in logs, email formatting<br>
+and so on. These guidelines are very similar to rules used by other open source<br>
+projects.<br>
+<br>
+Most importantly, the contents of the message should be carefully written to<br>
+convey the rationale of the change (without delving too much in detail). It<br>
+also should avoid being vague or overly specific. For example, "bits were not<br>
+set right" will leave the reviewer wondering about which bits, and why they<br>
+weren't right, while "Correctly set overflow bits in TargetInfo" conveys almost<br>
+all there is to the change.<br>
+<br>
+Below are some guidelines about the format of the message itself:<br>
+<br>
+* Separate the commit message into title, body and, if you're not the original<br>
+ author, a "Patch by" attribution line (see below).<br>
+<br>
+* The title should be concise. Because all commits are emailed to the list with<br>
+ the first line as the subject, long titles are frowned upon. Short titles<br>
+ also look better in `git log`.<br>
+<br>
+* When the changes are restricted to a specific part of the code (e.g. a<br>
+ back-end or optimization pass), it is customary to add a tag to the<br>
+ beginning of the line in square brackets. For example, "[SCEV] ..."<br>
+ or "[OpenMP] ...". This helps email filters and searches for post-commit<br>
+ reviews.<br>
+<br>
+* The body, if it exists, should be separated from the title by an empty line.<br>
+<br>
+* The body should be concise, but explanatory, including a complete<br>
+ reasoning. Unless it is required to understand the change, examples,<br>
+ code snippets and gory details should be left to bug comments, web<br>
+ review or the mailing list.<br>
+<br>
+* If the patch fixes a bug in bugzilla, please include the PR# in the message.<br>
+<br>
+* `Attribution of Changes`_ should be in a separate line, after the end of<br>
+ the body, as simple as "Patch by John Doe.". This is how we officially<br>
+ handle attribution, and there are automated processes that rely on this<br>
+ format.<br>
+<br>
+* Text formatting and spelling should follow the same rules as documentation<br>
+ and in-code comments, ex. capitalization, full stop, etc.<br>
+<br>
+For minor violations of these recommendations, the community normally favors<br>
+reminding the contributor of this policy over reverting. Minor corrections and<br>
+omissions can be handled by sending a reply to the commits mailing list.<br>
+<br>
Obtaining Commit Access<br>
-----------------------<br>
<br>
@@ -425,8 +478,9 @@ want the source code to be littered with<br>
by J. Random Hacker" (this is noisy and distracting). In practice, the revision<br>
control system keeps a perfect history of who changed what, and the CREDITS.txt<br>
file describes higher-level contributions. If you commit a patch for someone<br>
-else, please say "patch contributed by J. Random Hacker!" in the commit<br>
-message. Overall, please do not add contributor names to the source code.<br>
+else, please follow the attribution of changes in the simple manner as outlined<br>
+by the `commit messages`_ section.<br></blockquote><div><br></div><div>This sentence is garbled. How about "If you commit a patch for someone else, please give attribution to the original author as described in the `commit messages`_ section." or similar?</div></div></div></div>