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

[Reid Kleckner]

That seems mostly reasonable. I'd try to make it more concise, though. The
coding standards and developer policy docs should be short.

+Commit message
+--------------
+
+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 git repositories, such
as:

Maybe just: "Commit messages should be formatted according to the following
general guidelines:"

+* Separate the commit message into title and body.
+
+* The title should not have more than 80 columns, although 60/70 would be
+  better, since that'd fit better into a `git log` or an email subject.
+
+* The body, if it exists, should be separated from the title by an empty
line.
+
+* The body should be aligned to 80 columns and 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.

I don't think the suggestion to be concise is worth putting in the
document. More information is usually better.

+* `Attribution of Changes`_ should be in a separate line, after the end of
+  the body, as simple as "Patch by John Doe.".
+
+* Text formatting and spelling should follow the same rules as
documentation
+  and in-code comments, ex. capitalization, full stop, etc.

This point seems borderline, but I guess some people need it.

+While these rules match most of the cases, we're aware that some cases are
not
+covered, and that's why we don't think reverting patches with "bad" commit
+messages is a reasonable thing to do. We can, however, remind people of
this
+section of the policy for future reference.

I don't think this paragraph is needed, or it could be shortened to say
that these are not hard and fast rules and developers should use their own
editorial judgement.

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

> On 25 September 2014 00:56, Chandler Carruth <chandlerc at google.com> wrote:
> > We could certainly have a little guide for how to write awesome commit
> logs
> > and point people at it. But this is one of (many) aspects of getting
> ramped
> > up on the practices and patterns of the community. Not sure it ever
> really
> > makes sense to try to codify so much as explain it...
>
> I agree we shouldn't codify or enforce, but educate and remind people
> of good practices.
>
> How about the section attached?
>
> cheers,
> --renato
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20140925/7e9c1157/attachment.html>