ChangeLog love

[Geert Janssens]

On Thursday 16 May 2013 13:49:42 John Ralls wrote:
> On May 16, 2013, at 1:30 PM, Christian Stimming <christian at cstimming.de> wrote:
> > Am Donnerstag, 16. Mai 2013, 12:53:16 schrieb John Ralls:
> >> On May 16, 2013, at 12:35 PM, Mike Alexander <mta at umich.edu> wrote:
> >>> --On May 16, 2013 11:42:39 AM -0700 John Ralls <jralls at ceridwen.us> wrote:
> >>>>> 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.
> >>> 
> >>> I like something between these two extremes.  My personal model for the
> >>> best way to handle changelogs is BBEdit [1] from Barebones, although
> >>> doing it the way they do will take someone some time.  They manually
> >>> list all significant changes in a release with a very short summary
> >>> (sometimes humorous) of each change.  I don't know, but I suspect that
> >>> these are entered when someone checks in a change or closes a bug
> >>> report rather than all at once at release time.  I like this because it
> >>> quickly tells me what's new and whether the bug that has been annoying
> >>> me is fixed.>
> >>> 
> >>>       Mike
> >>> 
> >>> [1] <http://www.barebones.com/support/bbedit/arch_bbedit1053.html>
> >> 
> >> That looks like a digest: It's missing all of the "oops" commits that
> >> show
> >> up in a raw log. I usually do something similar in NEWS when I do a
> >> release, except that I separate design changes and bug fixes into
> >> separate
> >> sections. That follows a pattern of NEWS files I found when I started
> >> doing
> >> releases last year.
> > 
> > When we set up the ChangeLog generation a few years ago, we noticed that
> > the NEWS entries took quite some amount of work to be written together.
> > The basic problem is always that it takes manual work to summarize the
> > bunch of commits that belong together into single summary entries. At the
> > time we said we'd give up on this work and simply list all commits from
> > the SVN log. Unfortunately I still don't see a better solution at hand
> > that doesn't require a lot of manual work. Either we list everything, or
> > someone needs to write a list manually... If anyone (John?) volunteers to
> > do the manual writing for some time to come, that's fine and we should do
> > that. But if there's nobody volunteering for the manual list, I'd just
> > stick to the automatic ChangeLog for the releases and that's it.
> > 
> > Oh, and yes, it's purely meant for the release tarballs. There's no point
> > for those logs in anything except the released source tarballs. (And I
> > don't care if we change the format - any format is just fine.)
> 
> Less work is better, particularly when it comes to releases, but we need to
> write a release summary for the "news" item on the website anyway. The NEWS
> file is usually that plus a list of fixed bugs and a list of new or updated
> translations. A VCS log dump is pretty noisy in comparison, and will be
> more so as we get into the git way of making lots of small changes. On the
> other hand, if we also get in the git habit of doing nothing directly in
> trunk/master and merging instead of rebasing, then merge commit messages
> can have a nice summary that can go directly into news. Add a common
> notation for bug fixes and translations to a perl script and the amount of
> manual work at release time can bet pretty small.

This will again require developers to think upfront about their commit messages. In itself a 
good thing, but harder to enforce. I refer back here to our long discussion on a branching 
strategy in git, in which we also had some potential workflow improvements that depended 
on every developer adhering to it.

Other than that I like the idea of working with clean summary merge commit messages. 
We can't do this until we're pure git based though.

So for now I have limited myself to extend the ChangeLog generation code in the top level 
makefile so it now works from both an svn or a git repository.

We can revisit the ChangeLog revamp when we're pure git. Thanks all for your feedback.

Geert