[cfe-dev] Bikeshedding commit message policy - Round 3 - Fight!

[Chris Lattner]

> On Mar 15, 2015, at 1:33 PM, Renato Golin <renato.golin at linaro.org> wrote:
> 
> On 15 March 2015 at 20:22, Chris Lattner <clattner at apple.com> wrote:
>> Can you post the entire revised diff that you want to include?  Is it Diff 21913 on Phab?  If so, LGTM.
> 
> Hi Chris,
> 
> Here's the final version:
> 
> http://reviews.llvm.org/D8197

Looks fine to me, here are some suggested wording changes to make it flow better.  I also added a request to include bugzilla number.

-Chris

Commit messages
---------------

Although we don't enforce the format of commit messages, we prefer that
you follow these guidelines to help review, search in logs, email formatting and so on.
These guidelines are very similar to rules used by other open source projects.

Most importantly, the contents of the message should 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 "Correctly set overflow bits in TargetInfo" conveys 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" attribution line (see below).

* The title should be concise. Because all commits are emailed to the list with the
  first line as the subject, long titles are frowned upon.  Short titles also look better
  in `git log`.

* When the changes are restricted to a specific part of the code (e.g. 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 and searches for post-commit
  reviews.

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

* The body should be concise, but explanatory, including a complete
  reasoning.  Unless it is required to understand the change, examples,
  code snippets and gory details should be left to bug comments, web
  review or the mailing list.

* If the patch fixes a bug in bugzilla, please include the PR# in the message.

* `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
  format.

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

For minor violations of these recommendations, 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.