Re: git commit message conventions

[Florian Weimer <fweimer at redhat dot com>]

On 06/03/2015 09:01 AM, Torvald Riegel wrote:
> On Tue, 2015-06-02 at 18:19 -0700, Paul Eggert wrote:
>> Joseph Myers wrote:
>>> I propose that we adopt standard git commit message conventions that: the
>>> first line of a commit message is a short description of the commit, the
>>> next line is a blank line, and the rest of the commit message is the
>>> detailed description / rationale for the patch
>>
>> Many other GNU projects use this style, but with one further constraint: if you 
>> indent the entire commit message, and omit the 2nd (empty) line, the entire 
>> commit message must be a valid ChangeLog entry.
> 
> I'd much rather like to see the justification and motivation for the
> patch (ie, what we're currently putting in the emails accompanying a
> patch) be part of the git logs.  I'm that this is not the same as a
> Changelog entry's content, but it would be more valuable to me.

I completely agree, and I think Joseph's proposal goes in that direction.

There is the idea that you put explanations in source code comments, but
that only works reasonably well for new code.  For cleanups and
especially removals, there is often no reasonable place at all in the
source code where you can put an explanation of the change.

Martin's patch which sparked this discussion is a very good example. I
think:

  <https://sourceware.org/ml/libc-alpha/2015-05/msg00883.html>

It would be quite strange to put a comment in the header file which says
âwe used to define pthread_cleanup_{push,pop} here, but that led to bug
18435â.

-- 
Florian Weimer / Red Hat Product Security