Git ChangeLog policy for GCC Testsuite inquiry

H.J. Lu hjl.tools@gmail.com
Sat Jan 25 14:07:00 GMT 2020


On Fri, Jan 24, 2020 at 2:39 PM Paul Smith <paul@mad-scientist.net> wrote:
>
> 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.
>

Libgcrypt includes ChangeLog entries in git commit messages:

http://git.gnupg.org/cgi-bin/gitweb.cgi?p=libgcrypt.git

In each patch, commit log starts with ChangeLog entries without leading
TABs followed by separator line with -- and then commit message.   They
have a script to extract ChangeLog for release.

--
H.J.



More information about the Gcc mailing list