Re: Git ChangeLog policy for GCC Testsuite inquiry

[Paul Smith <paul@mad-scientist.net>]

On Fri, 2020-01-24 at 22:45 +0100, Jakub Jelinek wrote:
> > > In my experience the output of git log is a total mess so cannot
> > > replace ChangeLogs.  But we can well decide to drop ChangeLog for
> > > the testsuite.
> > 
> > Well, glibc has moved to extracting them from git, building
> > policies and scripts around that.  I'm pretty sure other
> > significant projecs are also extracting their ChangeLogs from git.
> > 
> > We could do the same, selecting some magic date as the cutover
> > point after which future ChangeLogs are extracted from GIT.  In
> > fact, that's precisely what I'd like to see us do.
> 
> We don't have a tool that can do it, not even get the boilerplate
> right. Yes, mklog helps, but it very often gets stuff wrong.  Not to
> mention that the text what actually changed can't be generated very
> easily.

I don't know if it counts as a significant project, but GNU make has
been doing this for years.

What I did was take the existing ChangeLogs and rename them to
ChangeLog.1 or whatever, then started with a new ChangeLog generated
from scratch from Git messages.

I use the gnulib build-aux/gitlog-to-changelog script to do it.  It
requires a little bit of discipline to get right; in particular you
have to remember that the Git commit message will be indented 8 spaces
in the ChangeLog, so you have to be careful that your commit messages
wrap at char 70 (or less) in your Git commit.

If you have Git hooks you could enforce a bit of formatting; for
example any line not indented by space must be <=70 chars long; this
allows people to use long lines for formatted content if they indent it
with a space or two.

Otherwise, it's the same as writing the ChangeLog and you only have to
do it once.

Just to note, the above script simply transcribes the commit message
into ChangeLog format.  It does NOT try to auto-generate ChangeLog-
style content (files that changed, functions, etc.) from the Git diff
or whatever.

There are a few special tokens you can add to your Git commit message
that get reformated to special changelog tokens like "(tiny change)"
etc.

As mentioned previously, it's very important that the commit message be
provided as part of the code review, and it is very much fair game for
review comments.  This is common practice, and a good idea because bad
commit messages are always a bummer, ChangeLog or not.