Re: original package changelogs
Some additional comments from me that may or may not be worth reading.
Paul Wise wrote:
> The GNU coding standards document doesn't recommend any specific
> format for NEWS files.
Right -- the format is (and has always been) free-form; it's usually a
nested list suitable for Emacs' outline-mode. Typically, the first
line of the excerpt for a specific release should match the regexp of
gnulib's `announce-gen' script which can be used to generate
announcement messages for any package, appending the relevant NEWS
snippet.
> If you use a version control system, there are cvs2cl, svn2cl, git2cl
> and probably other scripts to convert your commit messages into
> GNU-style ChangeLog files, no need to reinvent the wheel here.
All of them useless, IMHO.
There were long discussions on various GNU mailing lists when GNU
projects began migrating to modern VCSen (most often Git, but
sometimes Bzr and Mercurial) about what to do with ChangeLogs.
Perhaps the most interesting one is on bug-gnulib, when Bruno Haible
persuaded the other gnulib major contributors that ChangeLogs should
stay, and wrote a Git merge driver to facilitate merging when
conflicts occur (`git-merge-changelog' in gnulib).
The good thing about manually maintained ChangeLog files is that
modern GNU Emacsen will incrementally search through subsequent split
files (e.g. ChangeLog.1, ChangeLog.2, ...); it is easier for users who
use the package's VCS to download/track the source, but are not
ultimately familiar with the $VCS commands for history archaeology.
They are also nicely formatted, iff the standards are followed (`C-x 4
a' in Emacs does the right thing, and `C-c C-a' in a *vc-log* buffer
copies it, which is why maintenance of ChangeLog files was never
considered an extra burden, in the GNU project at least. The burden
now comes from typical dVCS usage/workflows because of conflicts and
inappropriate dates). In any case, all GNU packages should have a
ChangeLog in the release tarballs; whether it is autogenerated or not
is up to the maintainer.
Jim Meyering (main maintainer of coreutils and old-time GNUer) took
another approach -- he wrote a program (`gitlog-to-changelog') to
generate GNU-style changelog from Git commit logs (which should follow
strict commit discipline in such case) -- see a recent coreutils
changelog.gz for an example; it is almost undistinguishable from a
manually maintained file.
It is easy to maintain a ChangeLog (or a $VCS log that is GNU
ChangeLog-alike) with vc-dwim [1] -- this package is not tied to
Emacs. Someone familiar with Perl should probably ITP it :-))
Bzr has the option --gnu-changelog of the `log' command, but it has
the major disadvantage of duplicating entries when two subsequent
unrelated changes are made by a single person, i.e. it generates
2010-01-10 Yavor Doganov <yavor@gnu.org>
Fix memory leak in foo.
* src/foo.c (frobnicate): Free `bar'.
Reported by Joe User.
2010-01-10 Yavor Doganov <yavor@gnu.org>
Document baz-frobnicate.
* doc/foo.texi (baz-frobnicate Invocation): New node.
* NEWS: Update.
instead of
2010-01-10 Yavor Doganov <yavor@gnu.org>
Fix memory leak in foo.
* src/foo.c (frobnicate): Free `bar'.
Reported by Joe User.
Document baz-frobnicate.
* doc/foo.texi (baz-frobnicate Invocation): New node.
* NEWS: Update.
when the developer has (naturally) done two separate commits for the
above changes within the same day.
There are also some minor formatting bugs that are probably easy to
fix by the Bzr developers.
Mercurial has an option for its `log' command to show changes in
ChangeLog-style (which I happily use) but I'm not familiar enough with
this VCS to say if it could be used for automatic ChangeLog
generation, and what the constraints would be.
There is one serious obstacle in using a generated ChangeLog: For GNU
packages that require copyright assignment to the FSF (which in theory
is applicable for other packages that track contributors' changes and
require copyright assignments) the established practice is to mark the
changes with `(tiny change)', e.g. for Emacs where I didn't have
copyright assignment, a (real) example log entry is:
2008-10-24 Yavor Doganov <yavor@gnu.org> (tiny change)
* configure.in: Use `.' instead of `source' to source GNUstep.conf.
Exit with an error if `--with-ns' was specified but <AppKit/AppKit.h>
is not found. (Bug#1230)
When the contributor assigns copyright to the copyright holder
(usually FSF for GNU packages, but not always -- c.f. Bzr, Freetalk),
the "tiny change" bits are removed. They are just an indicator to
count the amount of the non-copyrightable contributions (which
accumulate).
Most VCSen do not allow modification of the commit logs (the
equivalent of `cvs admin ...', because they're integral part of the
change/history.
There are also packages that maintain more than one ChangeLog, for
clarity/convenience purposes -- f.i. (again) Emacs. Automatically
generating them at `make dist' time is probably possible, though.
[1] http://gnu.org/software/vc-dwim
Pietro Battiston wrote:
> Il giorno dom, 10/01/2010 alle 22.58 +0800, Paul Wise ha scritto:
> > The only standard I am aware of for that is the one described in
> > the GNU coding standards document[1].
>
> The suggested document doesn't mention releases, as far as I read.
That's because the ChangeLog has nothing to do with releases.
> I'd say that in general the main goal of a changelog is to map each
> _release_ to a set of changes (OK, and a date too), so that the
> reader can answer immediately to the questions:
No. As Paul said, the difference is often misunderstood. The purpose
of the ChangeLog is to identify changes + date + author when a
specific change happened. All changes, in a chronological manner, and
releases don't come into the picture at all.
debian/changelog for Debian packages is very similar (semantically) to
the GNU ChangeLog, except that it doesn't force a specific formatting
style other than the minimal prerequisites of dpkg-parsechangelog &
friends. (Well, the GNU ChangeLog doesn't enforce a style either.)
> - what's new in version x?
> - in which version was capability y introduced?
This is what NEWS is designed to be for. The ChangeLog should also
list these in a probably more technical language, where applicable (as
these "what's new" and "capability x" thingies actually appeared after
developers' modifications), but you should never rely on users reading
the ChangeLog. Developing a feature X may require N commits by N
developers; the release when feature X is described should contain a
NEWS entry summarizing it, with a pointer to the documentation if it
is not trivial. (This is, again, the usual practice within the GNU
project -- you can safely ignore it if you don't like it, but that's
the expectation of many users, AFAICT.)
From the user perspective, NEWS (for a Debian package,
/usr/share/doc/<package>/NEWS.gz) is the place to find this (upstream)
information. If it doesn't exist (because upstream doesn't maintain
such a file, for example), or the change is important enough to affect
other package(s) or typical usage of the package in question until the
upgrade, it is appropriate to add entries to debian/NEWS, which will
be shown up by apt-listchanges, etc. and is generally more prominent
for (Debian) users.
Reply to: