Bug#459427: changelog vs. NEWS handling
Hello,
This is one issue I think would be nice to have resolved so will
add my personal opinion below....
On Sun, Jan 06, 2008 at 02:55:00PM +0100, Peter Eisentraut wrote:
> Package: debian-policy
> Version: 3.7.3.0
> Severity: normal
>
> There is some lack of clarity in the policy or perhaps some confusion among
> packagers and thence inconsistencies among packages regarding the handling of
> upstream changelog files.
This ever growing inconsistency and confusion among packagers causes an
even bigger confusion among users. What can I as a user expect from
/usr/share/doc/package/changelog.gz ? Is it just random mumblings
because policy said the file had to be provided?
If that file is just going to be untrustworthy and potentially misleading
I better avoid opening it at all.
This is why I think /any/ resolution to this issue is important.
Ofcourse I have a personal favourite resolution, but as said /any/
resolution is better than prolonging the ongoing confusion.
> Policy says that upstream changelogs should be installed as
> /usr/share/doc/package/changelog.gz. Many packages, however, come
> with two kinds of changelogs: a source-level list of changes directed at
> developers, often called ChangeLog in a GNU-type package, and a user-level list
> of changes, sometimes called release notes, often in a file called NEWS in a
> GNU-type package.
>
> Debian packages appear to handle this in different ways: Some take the policy
> literally and install the ChangeLog as /usr/share/doc/package/changelog.gz and
> then install NEWS as additional documentation in /usr/share/doc/package/NEWS.gz
> or whatever the file is called in the particular case. Sometimes the source
> package doesn't come with a useful changelog, so they install NEWS or the
> release notes as /usr/share/doc/package/changelog.gz; others would then not
> install a "changelog" and install /usr/share/doc/package/NEWS.gz or some other
> name instead.
>
> This has two major problems: I think that installing a source-level change list
> is hardly ever useful for a binary package. Most users would probably rather
> read the release notes, but these are currently not be found at a uniform
> location. The intent behind all this was probably to give the package user a
> list of user-level changes. So in that sense most packages do a less than
> ideal job at the moment.
My personal opinion is that a changelog is something where every change
is guaranteed to be logged. (And that guarantee is basically just saying
that if it's ever noticed that a change was not logged, that's indeed a
bug.)
A NEWS file is something different to me in that it's a subset of the
changelog. Sometimes that subset might be equal to the entire changelog
set, but there's no guarantee that NEWS logs every change - rather the
opposite.
If someone hands me something and tells me it's a changelog then I want
to be able to trust the guarantee that nothing is hidden. The reason I
would be reading a changelog is often to try to figure out where a bug
might have sneaked in and that's often in the "uninteresting" changes.
If someone lied to me and gave me a censored changelog they're actively
wasting my time on misleading me.
I thus think a ChangeLog (or "source level changelog") should be
installed as changelog when available (and not when noone is available
or easily generatable).
When a NEWS (or "user level changelog") or similar is available that
should be installed as NEWS.
Additionally possibly clarify that when something is not available from
upstream people should *not* go out of their way to find something to
stuff in there. Many times I've heard that "policy says I have to"
when asking people why they're insisting on showing a bad lie down my
throut when they could have just left it out (because all
policy really said was just "...should ... if ...").
In other words, I support suggestion number 1 (with the extension of
standardizing the NEWS name along side changelog).
>
> I can think of three possibilities to address this:
>
> 1. Clarify the policy that a source-level changelog should be installed as
> /usr/share/doc/package/changelog.gz and user-level change lists/release notes
> should be installed as /usr/share/doc/package/NEWS.gz, whichever of these is
> available and deemed useful. This has the advantage that it is
> backward-compatible with respect to the changelog handling, and it would allow
> users to find the release notes under the familiar name "NEWS". It would also
> be somewhat consistent with the GNU names for these files and the handling of
> changelog.Debian vs. NEWS.Debian.
>
My personal preference does thus not go to option number 2 (or 3), but I
would still rather see either of them being used explicitly than leaving
things at the current status quo..... If option 2 or 3 is implemented
then atleast I can know that I should personally never care for
/usr/share/doc/package/changelog.gz again.
I also guess that the (overwhelming) majority of packages are still
shipping upstream ChangeLog as changelog and mostly just shipping
upstream NEWS as changelog when upstream ChangeLog is missing. I thus
think that implementing option number 2 would not be compliant with the
Policy Change Process point of "The change should not be too
disruptive". (OTOH when using should rather than must in the policy text
that by itself might guarantee a change is never really disruptive.)
> 2. Modify policy to say that source-level changelogs should not be installed
> unless there is some overriding reason. Also say that user-level release notes
> should be installed as /usr/share/doc/package/changelog.gz. This has the
> advantage that the currently used name "changelog" is preserved, but the
> disadvantage would be that it would take on a new meaning for many packages.
> It would also create an inconsistent naming scheme compared to the handling of
> changelog.Debian vs. NEWS.Debian.
>
> 3. Modify policy to say that source-level changelogs should not be installed
> unless there is some overriding reason. If they are installed, they should be
> installed as /usr/share/doc/package/changelog.gz. Add to policy that
> user-level release notes should be installed as /usr/share/doc/package/NEWS.gz.
> This has the advantage that it would preserve the meaning of the "changelog"
> file for most packages, but most packages could opt to drop them since they are
> probably useless in most cases. It would also create a new uniform policy for
> installing upstream release notes, which are currently handled inconsistently,
> and it would use the familiar name "NEWS" for that file, consistent with
> GNU-type packages and the name NEWS.Debian.
As a final word, I think my interpretation of ChangeLog as changelog and
NEWS as NEWS maps nicely onto how we handle debian/changelog and
debian/NEWS.
I don't think we need to add a source vs binary package abstraction.
People are already confused enough about when someone is talking about a
source or a binary package.
Considering we'll likely never reach a wide consensus on the
proper/perfect way of handling this, how do we move forward here?
Regards,
Andreas Henriksson
Reply to: