Subject: Re: [PATCH 1/3] SubmittingPatches: add convention of prefixing commit messages

From: Junio C Hamano <[email-masked]>
Date: Sun, 16 Dec 2012 15:15:10 -0800

Adam Spiers <[email-masked]> writes:

> Conscientious newcomers to git development will read SubmittingPatches
> and CodingGuidelines, but could easily miss the convention of
> prefixing commit messages with a single word identifying the file
> or area the commit touches.
>
> Signed-off-by: Adam Spiers <[email-masked]>
> ---
>  Documentation/SubmittingPatches | 8 ++++++++
>  1 file changed, 8 insertions(+)
>
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index 0dbf2c9..c107cb1 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -9,6 +9,14 @@ Checklist (and a short version for the impatient):
>  	- the first line of the commit message should be a short
>  	  description (50 characters is the soft limit, see DISCUSSION
>  	  in git-commit(1)), and should skip the full stop
> +	- it is also conventional in most cases to prefix the
> +	  first line with "area: " where the area is a filename
> +	  or identifier for the general area of the code being
> +	  modified, e.g.
> +	  . archive: ustar header checksum is computed unsigned
> +	  . git-cherry-pick.txt: clarify the use of revision range notation
> +	  (if in doubt which identifier to use, run "git log --no-merges"
> +	  on the files you are modifying to see the current conventions)

Thanks; I have to wonder if these details should be left in the
longer version to keep the "short" one short, though.

We should probably add "learn from good examples." (aka "read 'git
log' output and the pattern should be obvious to you") as the first
item to this list, too.

>  	- the body should provide a meaningful commit message, which:
>  	  . explains the problem the change tries to solve, iow, what
>  	    is wrong with the current code without the change.