[gentoo-dev] ChangeLog generation - pros and cons (council discussion request)

[Fabian Groffen]

Following up on the recent discussions about ChangeLogs, and what should
be in there, versus what not, this email tries to describe the pros and
cons of the frequently mentioned generation of ChangeLogs from the VCS
we use.

I would like the council to discuss the generation of ChangeLogs from
the VCS in the next meeting for which this message is in time.  I prefer
the council to decide upon whether or not generation of ChangeLogs is
desirable for Gentoo or not.  In this email, I will try to describe the
pros and cons, but I invite anyone else to contribute/discuss ideas.

I start from the assumption that generation of ChangeLogs is NOT limited
to any VCS.  Hence, I use generated ChangeLogs from CVS using my own
script attached to this email.  The packages I used were chosen
semi-randomly, but absolutely not for who committed to them.  Any
examples taken are by no means meant as personal attack to the
developers involved.

Simple pros I see mentioned:
- no more need for echangelog + repoman commit (identical message)
- no discussion on what to include or not (everything is in there)

Simple cons I see mentioned:
- useless information on removals of ebuilds/files
- useless information on whitespace changes
- inability to edit ChangeLog entries (typos, bug refs, etc.)

I'll ignore any technical cons regarding resources necessary to
generate, retain exact original format, etc.

Next thing, I compare original ChangeLogs to those generated.  I'll
highlight some differences that can be noticed.  I attached all
generated ChangeLogs to this email.  I apologise for the "Bob the
Builder" names, I was simply too lazy to map all devs to their real
names.  I'll report on my observations here first, such that the
remainder of this email is just the differences in the ChangeLogs.

1) it appears echangelog messages more than just a couple of times
   differ from the repoman commit messages; sometimes useful information
   is lost when just using the VCS logs
2) typo fixing on VCS-generated logs is sometimes necessary, but
   probably impossible
3) dates and new ebuilds generated from VCS are always correct,
   ChangeLog editting/echangelog -> commit delays can cause
   inconsitencies
4) package moves might lose all history for essentially the same files
5) entries for all commits show up, including those that weren't
   originally tracked in ChangeLog for some reason

If a move to VCS-generated ChangeLogs is to be made, it appears the
council has to decide that the following is desirable:
- a commit message is supposed to be always right/correct
- since the commit message is right, either
  - repoman commit runs echangelog, or
  - ChangeLogs are generated on current CVS as well
- any typos and incorrect refs, bugs, messages, etc. are accepted as
  drawback of the system that does not compare to its advantages
- it is accepted that all current information in the ChangeLogs gets
  lost in favour of the VCS commit messages
- there is no point in discussing what should be in or out of a
  ChangeLog, since by definition, "everything" is in (and tools should
  effectuate so ASAP)

If the council deems a separate ChangeLog file useful, they decide that:
- ChangeLog messages can (and sometimes should) be different from commit
  messages, as they are intended as information for users
- editting ChangeLog messages is necessary to emit the most correct
  information to our users at all times
- a clear policy is necessary on what is going in the ChangeLog and what
  not (like the current "common sense" discussions going on and the
  updated devmanual)
- basically nothing changes, and the whole idea of generating ChangeLogs
  from VCS is no longer a point of discussion


If I missed anything, please discuss.
The remainder of this email is just diffs with comments inline.

dev-vcs/git:
> --- ChangeLog   2011-05-31 08:47:22.000000000 +0200
> +++ ChangeLog.2 2011-06-02 09:47:58.177234000 +0200
> @@ -1,12 +1,12 @@
>  # ChangeLog for dev-vcs/git
>  # Copyright 1999-2011 Gentoo Foundation; Distributed under the GPL v2
> -# $Header: /var/cvsroot/gentoo-x86/dev-vcs/git/ChangeLog,v 1.95 2011/05/31 06:4
> 7:22 grobian Exp $
> +# $Header: this/file/is/a/generated/ChangeLog,v 1.1 2011/06/02 09:47:14 cvsps2changelog Exp $

The $Header line is likely going to be useless, and probably is best
removed.  Is there something useful that can be substituted here?

> -*git-1.7.3.2 (22 Oct 2010)
> +  22 Oct 2010; Bob the Builder <mduft@g.o> git-1.7.3.2.ebuild,
> +  -files/git-1.6.6.1-interix6.patch, -files/git-1.7.1-interix.patch,
> +  +files/git-1.7.3.2-interix.patch:
> +  added new (better :)) patch, removed obsolete ones.
>
> -  22 Oct 2010; Markus Duft <mduft@g.o> git-1.7.3.2.ebuild,
> -  +files/git-1.7.3.2-interix.patch,
> -  -files/git-1.6.6.1-interix6.patch,
> -  -files/git-1.7.1-interix.patch:
> -  removed obsolete patches, added a new one instead. the new patch matches
> -  more the spirit of upstream, and has been submitted there.
> +*git-1.7.3.2 (22 Oct 2010)
>
> -  11 Nov 2010; Sebastian Pipping <sping@g.o> git-9999.ebuild:
> -  Make live ebuild depend on asciidoc and xmlto independent of flag "doc"
> -  (bug #343063)
> +  11 Nov 2010; Bob the Builder <sping@g.o> git-9999.ebuild:
> +  dev-vcs/git: Fix dependencies of live ebuild (bug #343063)

(Slightly) different commit messages show up.  In this case, the
echangelog message was more explanatory than the commit message.  More
trivial, but not always innocent ones:

>    08 Jan 2011; Robin H. Johnson <robbat2@g.o> git-1.7.3.4-r1.ebuild:
> -  Backport bug #350330 automagic CVS to stable ebuild.
> +  Backport bug #350330 automagic perl to stable ebuild.
>
>    07 Jan 2011; Robin H. Johnson <robbat2@g.o> git-1.7.3.5-r1.ebuild,
>    +files/git-1.7.3.5-optional-cvs.patch:
> -  Bug #350330: Avoid automagic CVS.
> +  Bug #350330: Avoid automagic CVS. Need to port to 1.7.4 still.
>
>    07 Jan 2011; Robin H. Johnson <robbat2@g.o> +git-1.7.4_rc1-r1.ebuild,
>    git-9999.ebuild:
> -  Port the 1.7.3.5-r1 Prefix USE=python code to newer ebuilds since Prefix team
> -  has tested.
> +  Port the 1.7.3.5-r1 Prefix USE=python code to newer ebuilds since Prefix
> +  team ha tested.

It appears there were some typos here, and were fixed later to CVS.
There is no way to fix this.  CVS allows editing commit messages, but
that's disabled for obvious reasons.  I'm not sure about git, but from
what I've read, it becomes difficult (if not impossible) as soon as the
commit has been pushed.

> -*git-1.7.5.2 (30 May 2011)
> +*git-1.7.5.3 (30 May 2011)
>
>    30 May 2011; Robin H. Johnson <robbat2@g.o> +git-1.7.5.3.ebuild,
>    git-9999.ebuild:

A clear advantage of the generated ChangeLog; it gets the version right
even after long outstanding bumps.

> +*git-1.7.5_rc1 (07 Apr 2011)
> +*git-1.7.4.4 (07 Apr 2011)

Similar, but with dates.  This may be a timezone problem, though.

> +  08 Jan 2011; Bob the Builder <arfrever@g.o> git-1.7.3.5-r2.ebuild,
> +  git-1.7.4_rc1-r2.ebuild, git-9999.ebuild:
> +  Use $(PYTHON -a). EPYTHON is internal variable.
> +
> +  28 Dec 2010; Bob the Builder <mr_bones_@g.o> git-1.7.3.2-r1.ebuild,
> +  git-1.7.3.2.ebuild, git-1.7.3.3.ebuild, git-1.7.3.4-r1.ebuild,
> +  git-1.7.3.4.ebuild:
> +  whitespace

Another advantage, "missing" entries are inserted in the generated ChangeLog.

dev-php/magickwand (a pkgmoved package):
> --- ChangeLog   2011-04-10 19:37:54.000000000 +0200
> +++ ChangeLog.2 2011-06-02 10:32:41.290731000 +0200
> @@ -1,65 +1,10 @@
> -# ChangeLog for dev-php5/magickwand
> -# Copyright 1999-2010 Gentoo Foundation; Distributed under the GPL v2
> -# $Header: /var/cvsroot/gentoo-x86/dev-php/magickwand/ChangeLog,v 1.1 2011/04/10 17:37:54 olemarkus Exp $
> -
> -*magickwand-1.0.8-r1 (03 Nov 2010)
> -
> -  03 Nov 2010; Matti Bickel <mabi@g.o> +magickwand-1.0.8-r1.ebuild:
> -  create minor slotting compatible version
> -
> -*magickwand-1.0.8 (12 Apr 2010)
> -
> -  12 Apr 2010; <mabi@g.o> -magickwand-1.0.6.ebuild,
> -  -magickwand-1.0.7.ebuild, +magickwand-1.0.8.ebuild:
> -  version bump (bug #279836), older versions do not work with newer
> -  imagemagick
> -
> -  20 Mar 2009; Jorge Manuel B. S. Vicetto <jmbsvicetto@g.o>
> -  metadata.xml:
> -  Removing anant as a maintainer since he was retired.
> -
> -  12 Jun 2008; Christian Hoffmann <hoffie@g.o>
> -  files/imagemagick-pre-6.3.8-compat.patch:
> -  updated patch by Martin von Gagern <Martin.vGagern@×××.net> (bug 215671),
> -  previous version missed some MagickWand-config calls. magickwand-1.0.7
> -  should now really build with <imagemagick-6.3.8
> -
> -  09 Jun 2008; Christian Hoffmann <hoffie@g.o>
> -  +files/imagemagick-pre-6.3.8-compat.patch, magickwand-1.0.7.ebuild:
> -  adding patch by Martin von Gagern <Martin.vGagern@×××.net> (bug 215671) to
> -  allow for building against <imagemagick-6.3.8 again and adjust *DEPEND
> -  accordingly
> -
> -  08 Jun 2008; Christian Hoffmann <hoffie@g.o>
> -  magickwand-1.0.7.ebuild:
> -  bump imagemagick dependency to 6.3.9.7, bug 215671
> -
> -*magickwand-1.0.7 (03 Jun 2008)
> -
> -  03 Jun 2008; Luca Longinotti <chtekk@g.o> -magickwand-1.0.4.ebuild,
> -  -magickwand-1.0.5.ebuild, +magickwand-1.0.7.ebuild:
> -  Version bump.
> -
> -*magickwand-1.0.6 (11 Feb 2008)
> -
> -  11 Feb 2008; Raúl Porcel <armin76@g.o> +magickwand-1.0.6.ebuild:
> -  Version bump, from the php overlay
> -
> -*magickwand-1.0.5 (06 Oct 2007)
> -
> -  06 Oct 2007; Anant Narayanan <anant@g.o> +magickwand-1.0.5.ebuild:
> -  Bump to 1.0.5
> -
> -  27 Apr 2007; Steve Dibb <beandog@g.o> magickwand-1.0.4.ebuild:
> -  Add ~amd64, bug 175092
> -
> -  17 Apr 2007; Anant Narayanan <anant@g.o> magickwand-1.0.4.ebuild:
> -  Fix typo in PHP_EXT_INI and add explicit RDEPEND.
> -
> -*magickwand-1.0.4 (17 Apr 2007)
> -
> -  17 Apr 2007; Anant Narayanan <anant@g.o> +metadata.xml,
> -  +magickwand-1.0.4.ebuild:
> -  New ebuild for the MagickWand PHP extension; thanks to Matthew Schultz, bug
> -  #125593
> -
> +# ChangeLog for dev-php/magickwand
> +# Copyright 1999-2011 Gentoo Foundation; Distributed under the GPL v2
> +# $Header: this/file/is/a/generated/ChangeLog,v 1.1 2011/06/02 10:32:04 cvsps2changelog Exp $
> +
> +*magickwand-1.0.8-r1 (10 Apr 2011)
> +
> +  10 Apr 2011; Bob the Builder <olemarkus@g.o>
> +  +magickwand-1.0.8-r1.ebuild, +metadata.xml,
> +  +files/imagemagick-pre-6.3.8-compat.patch:
> +  Moved from dev-php5/magickwand

Obviously, all history is lost.  VCSs other than CVS might keep history
across moves here (svn, git, hg...), hence a "follow" could perhaps find
renames.  Question is if this can be detected in such a way that a
useful ChangeLog can be generated.  Will version bumps that are almost
identical copies, that show up as copies/renames cause issues here?

sys-devel/gcc-config:
> -  16 Mar 2008; Christian Heim <phreak@g.o> Manifest:
> -  Fixing the Manifest (emerge is complaining about missing
> -  $FILESDIR/wrapper-1.5.0.o).

This entry disappears because Manifest and ChangeLog changes are ignored.

> +  02 Jan 2009; Mike Frysinger <vapier@g.o> files/wrapper-1.5.1.c:
> +  optimize memory/string usage a bit more
>
> +  16 Mar 2008; Mike Frysinger <vapier@g.o> -gcc-config-1.3.13-r4.ebuild,
> +  -gcc-config-1.3.14.ebuild, -gcc-config-1.3.15-r1.ebuild,
> +  -files/gcc-config-1.3.13, -files/gcc-config-1.3.14, -files/gcc-config-1.3.15,
> +  -files/wrapper-1.4.7.c:
> +  old

Both entries are added in the generated ChangeLog variant.


-- 
Fabian Groffen
Gentoo on a different level