<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Thu, Sep 25, 2014 at 9:14 AM, 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:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><span class="">On 25 September 2014 16:52, Reid Kleckner <<a href="mailto:rnk@google.com">rnk@google.com</a>> wrote:<br>
> That seems mostly reasonable. I'd try to make it more concise, though. The<br>
> coding standards and developer policy docs should be short.<br>
<br>
</span>Right, version 2 attached. Does everyone agree with it?<br></blockquote><div><br></div><div>I don't specifically disagree with it, but I don't think all of it is useful. Let me be more  specific though:</div><div><br></div><div><div>+Commit message</div><div>+--------------</div><div>+</div><div>+Commit messages should be formatted according to the following general guidelines:</div><div><br></div><div>If these are just suggestions (and it sounds like they are) I think you shouldn't call it policy and you shouldn't use the phrasing "should be formatted". If folks don't read to the end, they would get the wrong impression. I would probably phrase this as:</div><div><br></div><div>"""</div><div>Here are some guidelines for writing and formatting commit messages. The goal is to help your commit logs fit well into the various pieces of infrastructure and be useful to other LLVM developers both when reviewing your code and when investigating commits at some date in the future to understand why a change was made.</div><div>"""</div><div><br></div><div>+</div><div>+* Separate the commit message into title and body.</div><div><br></div><div>Useful.</div><div><br></div><div>+</div><div>+* The title should not have more than 80 columns, although 50~70 would be</div><div>+  better, since that'd fit better into a `git log` or an email subject.</div><div><br></div><div>I don't think this is useful. Unless people are really diligent about trying to fit into 'git log' style displays, they won't actually abide by it. And if they are so diligent, they won't need the reminder.</div><div><br></div><div>+</div><div>+* The body, if it exists, should be separated from the title by an empty line.</div><div><br></div><div>This part is totally useful (although it could be combined with the first bullet point).</div><div><br></div><div>+  It should be aligned to 80 columns and may contain multiple paragraphs.</div><div><br></div><div>But I don't think telling people to do *this* will help -- either they wrap their text in their editor or they don't. If you want to do anything I would just make a single statement about column width along the lines of "as with the code in LLVM, commit logs are often best wrapped to 80 columns".</div><div><br></div><div>+</div><div>+* `Attribution of Changes`_ should be in a separate line, after the end of</div><div>+  the body, as simple as "Patch by John Doe.".</div><div><br></div><div>Totally useful.</div><div><br></div><div>+</div><div>+* Text formatting and spelling should follow the same rules as documentation</div><div>+  and in-code comments, ex. capitalization, full stop, etc.</div><div><br></div><div>Not really useful. The cost of formatting, punctuation, etc. mistakes in commit logs in near zero. We also can't fix them, so it doesn't seem to be terribly useful to spell out that fixes to these things are acceptable (the way it is useful for comments in code).</div></div><div><br></div><div><br></div><div>My other high-level concern is that I feel like this misses the most important piece of guidance about commit logs: it doesn't provide suggestions about what *content* to put into the commit log! If we're going to give suggestions for developers about how to write their commit logs, it should include this. I'm willing to take a stab at drafting a version of this that includes such suggestions later today if that helps?</div></div><br></div></div>