ChangeLog love

[John Ralls]

On May 16, 2013, at 10:17 AM, Geert Janssens <janssens-geert at telenet.be> wrote:

> I'm looking into the remaining bits preventing a full git migration when 2.6 will be released.
> 
> One item on the list is our automatic changelog generation in the toplevel's makefile. This 
> currently converts the svn log into a GNU style ChangeLog file.
> 
> It's easy to replicate something very similar based on the git logs in one single command:
> git log --format="%ai %aN %n%n%x09* %s%d%n"
> 
> There's two minor differences:
> - The date is formatted slightly differently (git includes time info, svn doesn't)
> - The author's name is full name, derived from authors e-mail (git) instead of unix login name 
> (svn)
> 
> I have no objections to these changes. If you do, please shout.

The time info is noise, but can be fixed with -ad --date='short'. Author's full name is a feature!

> 
> But looking into this raise a number of questions on the ChangeLog in general. I'll just ask 
> them here:
> 
> 1. Starting with the most basic one: why are we generating changelogs at all ? Both svn and 
> git have commands to easily extract all this information in one go. So I don't understand why 
> we want to keep this history checked in.
> 
> 2. For release tarballs, I can understand a bit better. The tarballs don't have all the revision 
> history available. But should each release really contain *all* the history ? Isn't it sufficient 
> and even more relevant to record only the changes that went into the release being shipped ? 
> Our current ChangLog format makes it a little confusing to figure out which change actually 
> got into which release version. Additionally our first release in each new development series 
> (like 2.5.0) usually takes more than a year before it gets released, compared to the branching 
> point. So for those releases the current ChangLog is always incomplete.
> 
> 3. Given the limited added value of the ChangeLog compared to git/svn logs, does it still 
> make sense to store the ChangeLog files in the repo ? They can be generated on the fly as 
> well when needed. A quick test on my git repo gives me the full changelog from the very first 
> commit in 1997 to present in less than 5 seconds...
> 
> 4. So considering all the above, wouldn't it make more sense to simply generate ChangeLogs 
> on the fly only for tarball generation ?
> 
> 
> These questions are not criticisms, but really intended to stimulate us to review or current 
> ChangeLog process. Is it still ok or time to improve ?

I'll go further: It makes far more sense for release tarballs to just have a digest of important changes in NEWS. We might have to fiddle autogen.sh to not whine about
ChangeLog if we delete it, but let's do it. The whole ChangeLog thing comes from
a time long ago when version control systems didn't have good logging. ChangeLog
was where commit messages went. It's totally redundant nowadays.

Regards,
John Ralls