Re: Git ChangeLog policy for GCC Testsuite inquiry

[Jeff Law <law at redhat dot com>]

On Mon, 2020-02-03 at 18:55 +0000, Richard Sandiford wrote:
> "H.J. Lu" <hjl.tools@gmail.com> writes:
> > 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.
> 
> How many people would we be catering for by generating changelogs at
> release time though?  It seems too low-level to be useful to users,
> and people wanting to track gcc development history at the source level
> would surely be better off using git (which e.g. makes it much easier to
> track changes to particular pieces of code).
> 
> Perhaps there are practical or policy reasons for not requiring everyone
> who wants to track gcc development history to build or install git.
> But if so, why not just include the output of "git log", with whatever
> options seem best?  (Probably --stat at least, to show the affected files.)
> 
> Like with the svn-to-git conversion, the less we change the way the
> history is presented, the less chance there is of something going wrong.
> And the idea is that git log should be informative enough for upstream
> developers, so surely it should be enough for others too.
I believe the ChangeLog is primarily a FSF requirement, hence
generating it from the SCM at release time seems reasonable.

ANd yes, even though I have been a regular ChangeLog user, I rely more
and more on the git log these days.

jeff