On Sun, Jan 06, 2008 at 02:55:00PM +0100, Peter Eisentraut wrote:
> 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. 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.
I agree with this rationale.
> 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.
>
> 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.
I would prefer not installing the source-level changelogs, then the
logical next step would be installing hand-written changelogs as
changelog.gz. I think at least some of packages where there is no
source-level changelog in the upstream source already install hand-written
changelogs (whatever their upstream name) as changelog.gz.
dh_installchangelogs(1) already installs one of the following as changelog.gz:
{.,doc,docs}/{changelog,changes,changelog.txt,changes.txt,history,history.txt,changelog.md}
At least some of these files are usually hand-written.
So, I want to hear other opinions but my opinion is closer to the option 2
above.
--
WBR, wRAR
Attachment:
signature.asc
Description: Digital signature