[llvm] r232334 - Adding commit msg guidelines to dev policy

[Richard Smith]

On Sun, Mar 15, 2015 at 2:15 PM, Renato Golin <renato.golin at linaro.org>
wrote:

> Author: rengolin
> Date: Sun Mar 15 16:15:48 2015
> New Revision: 232334
>
> URL: http://llvm.org/viewvc/llvm-project?rev=232334&view=rev
> Log:
> Adding commit msg guidelines to dev policy
>
> After much bike shed discussions, we seem to agree to a few loose
> but relevant guidelines on how to prepare a commit message. It also
> points the attribution section to the new commit messages section
> to deduplicate information.
>
> Modified:
>     llvm/trunk/docs/DeveloperPolicy.rst
>
> Modified: llvm/trunk/docs/DeveloperPolicy.rst
> URL:
> http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/DeveloperPolicy.rst?rev=232334&r1=232333&r2=232334&view=diff
>
> ==============================================================================
> --- llvm/trunk/docs/DeveloperPolicy.rst (original)
> +++ llvm/trunk/docs/DeveloperPolicy.rst Sun Mar 15 16:15:48 2015
> @@ -275,6 +275,59 @@ reverted. This is necessary when the cha
>  progress. The developer is welcome to re-commit the change after the
> problem has
>  been fixed.
>
> +.. _commit messages:
> +
> +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.
> +
>  Obtaining Commit Access
>  -----------------------
>
> @@ -425,8 +478,9 @@ want the source code to be littered with
>  by J. Random Hacker" (this is noisy and distracting). In practice, the
> revision
>  control system keeps a perfect history of who changed what, and the
> CREDITS.txt
>  file describes higher-level contributions. If you commit a patch for
> someone
> -else, please say "patch contributed by J. Random Hacker!" in the commit
> -message. Overall, please do not add contributor names to the source code.
> +else, please follow the attribution of changes in the simple manner as
> outlined
> +by the `commit messages`_ section.
>

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?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20150316/556ba8ab/attachment.html>