[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Bug#459427: marked as done (changelog vs. NEWS handling)

Your message dated Thu, 02 Aug 2018 02:43:10 +0000
with message-id <E1fl3a2-0004rX-Qw@fasolo.debian.org>
and subject line Bug#459427: fixed in debian-policy 4.2.0.0
has caused the Debian Bug report #459427,
regarding changelog vs. NEWS handling
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
Bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact owner@bugs.debian.org
immediately.)


-- 
459427: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=459427
Debian Bug Tracking System
Contact owner@bugs.debian.org with problems
--- Begin Message --- 
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.  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 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.

--- End Message ---
--- Begin Message --- 
Source: debian-policy
Source-Version: 4.2.0.0

We believe that the bug you reported is fixed in the latest version of
debian-policy, which is due to be installed in the Debian FTP archive.

A summary of the changes between this version and the previous one is
attached.

Thank you for reporting the bug, which will now be closed.  If you
have further comments please address them to 459427@bugs.debian.org,
and the maintainer will reopen the bug report if appropriate.

Debian distribution maintenance software
pp.
Sean Whitton <spwhitton@spwhitton.name> (supplier of updated debian-policy package)

(This message was generated automatically at their request; if you
believe that there is a problem with it please contact the archive
administrators by mailing ftpmaster@ftp-master.debian.org)


-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

Format: 1.8
Date: Thu, 02 Aug 2018 09:43:33 +0800
Source: debian-policy
Binary: debian-policy
Architecture: source
Version: 4.2.0.0
Distribution: unstable
Urgency: medium
Maintainer: Debian Policy Editors <debian-policy@lists.debian.org>
Changed-By: Sean Whitton <spwhitton@spwhitton.name>
Description:
 debian-policy - Debian Policy Manual and related documents
Closes: 459427 628515 813471 873456 876075 879048 886258
Changes:
 debian-policy (4.2.0.0) unstable; urgency=medium
 .
   * Policy: Standards-Version field is mandatory
     Wording: Sean Whitton <spwhitton@spwhitton.name>
     Seconded: Holger Levsen <holger@layer-acht.org>
     Seconded: Bill Allombert <ballombe@debian.org>
     Closes: #886258
   * Policy: Builds should be verbose & 'terse' DEB_BUILD_OPTIONS flag
     Wording: Sean Whitton <spwhitton@spwhitton.name>
     Seconded: Andrey Rahmatullin <wrar@debian.org>
     Seconded: David Bremner <bremner@debian.org>
     Seconded: Ian Jackson <ijackson@chiark.greenend.org.uk>
     Closes: #628515
   * Policy: Required targets may attempt some network access
     Wording: Sean Whitton <spwhitton@spwhitton.name>
     Seconded: David Bremner <bremner@debian.org>
     Seconded: Osamu Aoki <osamu@debian.org>
     Seconded: Niels Thykier <niels@thykier.net>
     Closes: #813471
   * Policy: Installation of upstream release notes and changelogs
     Wording: Sean Whitton <spwhitton@spwhitton.name>
     Seconded: Holger Levsen <holger@layer-acht.org>
     Seconded: Russ Allbery <rra@debian.org>
     Seconded: David Bremner <bremner@debian.org>
     Closes: #459427
 .
   * Add a third paragraph to 1.3.3 encouraging the submission of patches
     to document new techniques sooner rather than later, while making it
     clear that updating the Policy Manual should never block making other
     improvements to Debian.
   * Tweak wording in a sentence in 1.1.
   * Add a note to the README about why salsa merge requests are turned off.
 .
   * Stop installing policy-1.html because Sphinx's singlehtml output is
     too buggy at present (Closes: #873456, #876075, #879048).
     See also #877367.  Thanks to Paul Wise for switching the web mirrors
     away from policy-1.html.
 .
   * license-count: improve regex for some Creative Commons licenses.
     Thanks Jonathan Dowland for the patch.
   * Fix some indentation in ch-archive.rst.
     Thanks Hideki Yamane for the patch.
Checksums-Sha1:
 249930acf77fdeed3af5e9594ecf07d4bfe754d6 2001 debian-policy_4.2.0.0.dsc
 3dbbdfba9560e36084cffe04b781de8070cccaaf 462264 debian-policy_4.2.0.0.tar.xz
Checksums-Sha256:
 f7301ef0bf117c1bbcb06f53abc68a13788f26f21693a15726c4b34e4707ed01 2001 debian-policy_4.2.0.0.dsc
 ddb0d25d884d50784a0b1703ce6f17cadd4644c97c56ee30ce2205dd490188ea 462264 debian-policy_4.2.0.0.tar.xz
Files:
 81b49a008902e875a5a6866d4d776c77 2001 doc optional debian-policy_4.2.0.0.dsc
 eab84ea8b21d72b76303299c3296af46 462264 doc optional debian-policy_4.2.0.0.tar.xz

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEm5FwB64DDjbk/CSLaVt65L8GYkAFAltiZBkACgkQaVt65L8G
YkCoMA//Yo3S7Fhoq/1Atovtjty7EUB3VAOIl9P6V6Pq8cnaGIygqngc/LunyYKF
GdVgad0ZkH3dEwiCI5OBYpFHMXtyqqZFRyFN7KOrC1nm42OL4kyNSPlYLt5pPEeu
/qfddkKvad6g0JVI9od7n2V14DGaRxayR71oJBHOPOl1vltolYNI5XZQUQEJeupm
fcQf73aEnMWrXVD4EaGUWubIT+9mmfIea5kqhq8k97mn2iS4r9dspVHuwp31oxvP
Qz3qyr/g1mtZGCWXHOkXHEUNIVQXiDXQFeZOWUkH+DQtiLmtz70zOBt6BrbIFJYb
sMyICToVdYonSwe2HeaYzKFHD+4kaX+R/s4UxqDKUU/zc8C1VEjLX/9+NxBdkLM9
ZavgKoc7LsMeLL7x/rSQlMk4GHaZ4MBGI5YshkCB3qeoUoBVM1JnoEuIXOHGHkJH
7ZljQI3mvg4LbiGmur94+Jz3tjoGL0MrupUKumSFEOgdAM/H8k/2NkDqtafdHIYE
Xz0vl8xgeZbh6ppszd6z4IwugWgP8S12f4upJ75cnC61g4TubaitPvV+g8GPXFXK
8NLCsQKmv23NmETKEWwKPlMMymYxl+BwfnWjDbGOkMklVccrK1HOhcHIpGuIYbi2
s4zJB9QGmXV21fkEap7xn0ycmYlqNYqPZB4GEd1v8Yr7NSPq05c=
=4sn1
-----END PGP SIGNATURE-----

--- End Message ---
Reply to: