[LLVMdev] [cfe-dev] Commit message policy?

[Chandler Carruth]

On Thu, Sep 25, 2014 at 9:14 AM, Renato Golin <renato.golin at linaro.org>
wrote:

> On 25 September 2014 16:52, Reid Kleckner <rnk at google.com> wrote:
> > That seems mostly reasonable. I'd try to make it more concise, though.
> The
> > coding standards and developer policy docs should be short.
>
> Right, version 2 attached. Does everyone agree with it?
>

I don't specifically disagree with it, but I don't think all of it is
useful. Let me be more  specific though:

+Commit message
+--------------
+
+Commit messages should be formatted according to the following general
guidelines:

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:

"""
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.
"""

+
+* Separate the commit message into title and body.

Useful.

+
+* The title should not have more than 80 columns, although 50~70 would be
+  better, since that'd fit better into a `git log` or an email subject.

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.

+
+* The body, if it exists, should be separated from the title by an empty
line.

This part is totally useful (although it could be combined with the first
bullet point).

+  It should be aligned to 80 columns and may contain multiple paragraphs.

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".

+
+* `Attribution of Changes`_ should be in a separate line, after the end of
+  the body, as simple as "Patch by John Doe.".

Totally useful.

+
+* Text formatting and spelling should follow the same rules as
documentation
+  and in-code comments, ex. capitalization, full stop, etc.

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).


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?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20140925/63c9608d/attachment.html>