More consistency for Git log messages?

More consistency for Git log messages?

[Gerald Pfeifer]

Having spent a bit more time with GCC sources (as opposed to wwwdocs) 
recently and looking for prior art to guide me, I noticed there's a 
lot of options to specific the ChangeLog file(s) to use.

And correspondingly a lot of inconsistency.

Right now we seem to allow for

 1. gcc/cp/ChangeLog
 2. gcc/cp/ChangeLog:
 3. gcc/cp
 4. gcc/cp:
 5. gcc/cp/

and probably more.

Can we streamline this a bit and converge on one of the forms 3-5?

Personally I'd suggest 3 (the shortest) or 5 (the directory), but whatever 
... as long as things become more consistent, which is easier on newbies
and reading logs (or automatically processing them later on).

Gerald

Re: More consistency for Git log messages?

[Jonathan Wakely]

On Mon, 28 Dec 2020, 23:55 Gerald Pfeifer, <gerald@pfeifer.com> wrote:

> Having spent a bit more time with GCC sources (as opposed to wwwdocs)
> recently and looking for prior art to guide me, I noticed there's a
> lot of options to specific the ChangeLog file(s) to use.
>
> And correspondingly a lot of inconsistency.
>
> Right now we seem to allow for
>
>  1. gcc/cp/ChangeLog
>  2. gcc/cp/ChangeLog:
>  3. gcc/cp
>  4. gcc/cp:
>  5. gcc/cp/
>
> and probably more.
>

We also allow not specifying the directory at all, if it can be deduced
from the changed files.



> Can we streamline this a bit and converge on one of the forms 3-5?
>
> Personally I'd suggest 3 (the shortest) or 5 (the directory), but whatever
> ... as long as things become more consistent, which is easier on newbies
> and reading logs (or automatically processing them later on).
>

We already process them automatically.

It's worth noting that some people generate then automatically too, and the
mklog.py hook uses form 2 IIRC.

Re: More consistency for Git log messages?

[Segher Boessenkool]

On Tue, Dec 29, 2020 at 12:54:53AM +0100, Gerald Pfeifer wrote:
> Having spent a bit more time with GCC sources (as opposed to wwwdocs) 
> recently and looking for prior art to guide me, I noticed there's a 
> lot of options to specific the ChangeLog file(s) to use.
> 
> And correspondingly a lot of inconsistency.
> 
> Right now we seem to allow for
> 
>  1. gcc/cp/ChangeLog
>  2. gcc/cp/ChangeLog:
>  3. gcc/cp
>  4. gcc/cp:
>  5. gcc/cp/
> 
> and probably more.
> 
> Can we streamline this a bit and converge on one of the forms 3-5?
> 
> Personally I'd suggest 3 (the shortest) or 5 (the directory), but whatever 
> ... as long as things become more consistent, which is easier on newbies
> and reading logs (or automatically processing them later on).

I have done 5 for many years.  The colon isn't a great choice imo, the
changelog messages themselves contain colons as well, and it is nice to
have this visually distinct.  "gcc/" looks a lot better than just "gcc"
(and similar for other dirs, but less bad).  (I often left it out
completely if it would have been just gcc/, since it was just for
humans, pretty much all of the changelog format is not machine-parseable
without AI advances anyway, so heh).

But 1 and 2 are much worse indeed :-)  Unnecessary words distract from
the actual content.


Segher

Re: More consistency for Git log messages?

[H.J. Lu]

On Wed, Dec 30, 2020 at 6:21 AM Segher Boessenkool
<segher@kernel.crashing.org> wrote:
>
> On Tue, Dec 29, 2020 at 12:54:53AM +0100, Gerald Pfeifer wrote:
> > Having spent a bit more time with GCC sources (as opposed to wwwdocs)
> > recently and looking for prior art to guide me, I noticed there's a
> > lot of options to specific the ChangeLog file(s) to use.
> >
> > And correspondingly a lot of inconsistency.
> >
> > Right now we seem to allow for
> >
> >  1. gcc/cp/ChangeLog
> >  2. gcc/cp/ChangeLog:
> >  3. gcc/cp
> >  4. gcc/cp:
> >  5. gcc/cp/
> >
> > and probably more.
> >
> > Can we streamline this a bit and converge on one of the forms 3-5?
> >
> > Personally I'd suggest 3 (the shortest) or 5 (the directory), but whatever
> > ... as long as things become more consistent, which is easier on newbies
> > and reading logs (or automatically processing them later on).
>
> I have done 5 for many years.  The colon isn't a great choice imo, the
> changelog messages themselves contain colons as well, and it is nice to
> have this visually distinct.  "gcc/" looks a lot better than just "gcc"
> (and similar for other dirs, but less bad).  (I often left it out
> completely if it would have been just gcc/, since it was just for
> humans, pretty much all of the changelog format is not machine-parseable
> without AI advances anyway, so heh).
>
> But 1 and 2 are much worse indeed :-)  Unnecessary words distract from
> the actual content.

I also vote for option 5.

-- 
H.J.

Re: More consistency for Git log messages?

[Jakub Jelinek]

On Tue, Dec 29, 2020 at 12:54:53AM +0100, Gerald Pfeifer wrote:
> Having spent a bit more time with GCC sources (as opposed to wwwdocs) 
> recently and looking for prior art to guide me, I noticed there's a 
> lot of options to specific the ChangeLog file(s) to use.
> 
> And correspondingly a lot of inconsistency.
> 
> Right now we seem to allow for
> 
>  1. gcc/cp/ChangeLog
>  2. gcc/cp/ChangeLog:
>  3. gcc/cp
>  4. gcc/cp:
>  5. gcc/cp/
> 
> and probably more.
> 
> Can we streamline this a bit and converge on one of the forms 3-5?

Why?
Different people have different styles (usually from years before the git
conversion) and that is reflected in what the checking as well as ChangeLog
generation scripts allow or reject. One style is also not to specify the
ChangeLog files at all (something I prefer to use when it is possible).
All that matters is whether the scripts can handle it or not and that is
checked at git push time.

	Jakub

Re: More consistency for Git log messages?

[Martin Sebor]

On 12/29/20 1:49 AM, Jonathan Wakely via Gcc wrote:
> On Mon, 28 Dec 2020, 23:55 Gerald Pfeifer, <gerald@pfeifer.com> wrote:
> 
>> Having spent a bit more time with GCC sources (as opposed to wwwdocs)
>> recently and looking for prior art to guide me, I noticed there's a
>> lot of options to specific the ChangeLog file(s) to use.
>>
>> And correspondingly a lot of inconsistency.
>>
>> Right now we seem to allow for
>>
>>   1. gcc/cp/ChangeLog
>>   2. gcc/cp/ChangeLog:
>>   3. gcc/cp
>>   4. gcc/cp:
>>   5. gcc/cp/
>>
>> and probably more.
>>
> 
> We also allow not specifying the directory at all, if it can be deduced
> from the changed files.

That's a nice feature I didn't even know about!

>> Can we streamline this a bit and converge on one of the forms 3-5?
>>
>> Personally I'd suggest 3 (the shortest) or 5 (the directory), but whatever
>> ... as long as things become more consistent, which is easier on newbies
>> and reading logs (or automatically processing them later on).
>>
> 
> We already process them automatically.
> 
> It's worth noting that some people generate then automatically too, and the
> mklog.py hook uses form 2 IIRC.

I believe you're right.  I use the script to generate a template
for my first patch.  For subsequent revisions I copy the template
from the first one and edit it by hand (and often mess things up,
making the commit hook complain).

I rarely read ChangeLogs so I'm not bothered by inconsistencies
in it but I can relate to those who do and are.  I'm not against
increasing the consistency of the format just as long as it
doesn't make the commit procedure more onerous.  Changing
the commit hook to massage the ChangeLog lines (and any other
minutiae) into a preferred format would do that.

Martin

Re: More consistency for Git log messages?

[Martin Liška]

On 12/30/20 3:49 PM, Jakub Jelinek via Gcc wrote:
> On Tue, Dec 29, 2020 at 12:54:53AM +0100, Gerald Pfeifer wrote:
>> Having spent a bit more time with GCC sources (as opposed to wwwdocs)
>> recently and looking for prior art to guide me, I noticed there's a
>> lot of options to specific the ChangeLog file(s) to use.
>>
>> And correspondingly a lot of inconsistency.
>>
>> Right now we seem to allow for
>>
>>   1. gcc/cp/ChangeLog
>>   2. gcc/cp/ChangeLog:
>>   3. gcc/cp
>>   4. gcc/cp:
>>   5. gcc/cp/
>>
>> and probably more.
>>
>> Can we streamline this a bit and converge on one of the forms 3-5?
> 
> Why?
> Different people have different styles (usually from years before the git
> conversion) and that is reflected in what the checking as well as ChangeLog
> generation scripts allow or reject. One style is also not to specify the
> ChangeLog files at all (something I prefer to use when it is possible).
> All that matters is whether the scripts can handle it or not and that is
> checked at git push time.

Hello.

As the author of the GCC changelog parser, I agree with Jakub that we should
support all the formats. Now having the parser, I don't see a benefit bringing
more restrictions for developers.

Martin

> 
> 	Jakub
>