Bug#459427: changelog vs. NEWS handling
On Tue, 28 Nov 2017 at 23:01:08 -0500, Jeremy Bicha wrote:
> As others have said, running 'git log' is far more useful than a
> complete changelog and in my experience, most projects these days
> outside of GNU don't bother shipping changelogs.
Many of those projects that do ship a ChangeLog generate it from
`git log`, so it can't possibly be more useful than `git log` (except
for the property that it's already on your system; but that's a
double-edged sword, because the detailed changelog of the packages that
you're currently investigating are maybe useful, the detailed changelogs
of all other packages are a waste of space, and those roles can change
at any time).
> Most of my Debian and Ubuntu work involves GNOME packaging. For the
> most part, GNOME components ships NEWS files which are much more
> interesting for users or developers to read for highlights of what
> changed when.
This is in line with the roles of NEWS and ChangeLog in the GNU Coding
Standards, which is perhaps a more canonical reference than "what
GNOME does".
> I believe Policy's advice to install upstream changelogs should be
> dropped. In its place, I think a recommendation to ship NEWS files in
> /usr/share/doc/ would be useful. Notably, debhelper does not currently
> install NEWS files unless explicitly told to.[3]
How about something like this?
"""
If the upstream project provides a user-facing summary of changes
or release notes (often named NEWS, for example in projects that
follow the GNU Coding Standards), then it should be made accessible
as /usr/share/doc/<package>/NEWS.gz in gzip-compressed plain text. If
the summary of changes is distributed in HTML, it should be made
available in that form as /usr/share/doc/<package>/NEWS.html.gz, and
a plain text NEWS.gz should be generated from it using, for example,
lynx -dump -nolist.
If the upstream project only provides a detailed change log
(often named ChangeLog, for example in projects that follow the GNU
Coding Standards), then it [TODO: should? may?] be made accessible as
/usr/share/doc/<package>/changelog.gz in gzip-compressed plain text.
If the detailed change log is distributed in HTML, it [should? may?]
be made available in that form as
/usr/share/doc/<package>/changelog.html.gz; if so, a plain text
changelog.gz should be generated from it.
If the upstream project provides both a user-facing summary of changes
and a detailed change log, then latter should not usually be provided
in binary packages.
If the upstream changelog files do not already conform to this naming
convention, then this may be achieved either by renaming the files,
or by adding a symbolic link, at the maintainer’s discretion.
"""
I suspect the bits about .html.gz should also say .html, because typical
web browsers don't display file:///some/path/foo.html.gz the way we'd
want, and shipping NEWS instead of ChangeLog limits the space wasted by
lack of compression.
Looking further back in the history of this bug, I think this agrees
with option 2 from the mail that opened the bug, except that a few
people wanted to install the upstream NEWS as changelog.gz instead of
NEWS.gz (option 3).
I'm not sure what Policy should recommend for the case where an upstream
distributes a detailed ChangeLog but no user-facing NEWS. One point of
view is that the detailed ChangeLog is user-hostile but better than
nothing; another is that it's probably a waste of space, because anyone
doing sufficient archaeology to be willing to read a detailed ChangeLog
should be going straight to the project's VCS repository.
> I think the idea of renaming NEWS to changelog (as is done by
> dh_installchangelogs NEWS) is wrong, because it goes against people's
> understanding of what a changelog generally looks like.
At the risk of making more packages immediately buggy, I think I agree
with this, and hence prefer option 2 over option 3. If packages continue
to have both files (perhaps because this particular upstream writes a
sufficiently abbreviated summary in NEWS that referring to the detailed
changelog is more frequently necessary), then they should keep their
current/historical names NEWS.gz and changelog.gz; and if only one is
installed, then it should have the same name as if both were, to create
the right expectation about their contents.
This nicely mirrors NEWS.Debian.gz and changelog.Debian.gz, too.
smcv
Reply to: