[llvm] r232334 - Adding commit msg guidelines to dev policy
richard at metafoo.co.uk
Mon Mar 16 14:05:23 PDT 2015
On Sun, Mar 15, 2015 at 2:15 PM, Renato Golin <renato.golin at linaro.org>
> Author: rengolin
> Date: Sun Mar 15 16:15:48 2015
> New Revision: 232334
> URL: http://llvm.org/viewvc/llvm-project?rev=232334&view=rev
> 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
> --- 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
> +and so on. These guidelines are very similar to rules used by other open
> +Most importantly, the contents of the message should be carefully written
> +convey the rationale of the change (without delving too much in detail).
> +also should avoid being vague or overly specific. For example, "bits were
> +set right" will leave the reviewer wondering about which bits, and why
> +weren't right, while "Correctly set overflow bits in TargetInfo" conveys
> +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
> + 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
> + 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
> +* 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
> +* `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
> + and in-code comments, ex. capitalization, full stop, etc.
> +For minor violations of these recommendations, the community normally
> +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
> control system keeps a perfect history of who changed what, and the
> file describes higher-level contributions. If you commit a patch for
> -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
> +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...
More information about the llvm-commits