Bug#459427: Patch seeking seconds on changelog vs. NEWS handling

[Sean Whitton]

Hello Ian,

On Tue 14 Aug 2018 at 05:48PM +0100, Ian Jackson wrote:

> I think part of the difficulty we are having with this is by failing
> to have a kind of contextual introduction.

I see what you are trying to do, but there are two immediate
difficulties:

- Debian itself uses the term 'changelog' in a non-standard way -- the
  way that dev-ref says we are meant to use debian/changelog makes it
  sound like release notes.

  This is the main reason I avoided saying what release notes and
  changelogs are throughout this bug.

- there are numerous claims in your text on which we could not establish
  consensus; for example:

>   Code changelogs are not very useful without the source code.  They
>   should not normally be installed in the binary package unless this
>   is required by the package's licence.

In any case, this bug (#459427) is closed, so if you want to work on
this, you should file a new bug.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#459427: Patch seeking seconds on changelog vs. NEWS handling [and 1 more messages]

[Ian Jackson]

Simon McVittie writes ("Bug#459427: Patch seeking seconds on changelog vs. NEWS 
handling"):
> Debian packages have a Debian changelog and (when the source package
> is included, without which we are not GPL-compliant anyway) a Debian
> diff/tar, so there is certainly a prominent notice that we have modified
> it. I am not a lawyer, but I believe this is enough for the letter and
> spirit of the license: it tells a user "if you are looking for an
> unmodified GNU Hello, this is not it".

I agree.  So maybe my suggested text should read something like this:

Ian Jackson writes ("Re: Bug#459427: Patch seeking seconds on changelog vs. 
NEWS handling"):
>   Code changelogs are not very useful without the source code.  They
>   should not normally be installed in the binary package unless this
>   is required by the package's licence.

   (Note that this is NOT
required by any version of the GNU GPL.)

>  When they are installed, they
>   should be installed as /usr/share/doc/PACKAGE/changelog.gz.

Ian.

-- 
Ian JacksonThese opinions are my own.

If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.

Bug#459427: Patch seeking seconds on changelog vs. NEWS handling

[Ian Jackson]

Sean Whitton writes ("Bug#459427: Patch seeking seconds on changelog vs. NEWS 
handling"):
> +If an upstream release notes file is available, containing a summary
> +of changes between upstream releases intended for end users of the
> +package and often called ``NEWS``, it should be accessible as
> +``/usr/share/doc/package/NEWS.gz``.  An older practice of installing
> +the upstream release notes as ``/usr/share/doc/package/changelog.gz``
> +is permitted but deprecated.

I think part of the difficulty we are having with this is by failing
to have a kind of contextual introduction.

How about:

  Upstreams provide information about changes between upstream ersions
  in a variety of formats and with a variety of content.  Typically
  there are two distinct kinds of change informatiion:

   * Release notes style: describes user-visible changes such as new
 features, backwards compatibility issues, and perhapz significant
 bugfixes.  Examples: [...]

   * Code changelog style: lists all changes made to the source code,
 even ones which are not user-visible, often by reference to
 source code filenames.  Examples: [...]

  Release notes are useful to users.  If available, they should be
  installed as /usr/share/doc/PACKAGE/NEWS.gz.

  Code changelogs are not very useful without the source code.  They
  should not normally be installed in the binary package unless this
  is required by the package's licence.  When they are installed, they
  should be installed as /usr/share/doc/PACKAGE/changelog.gz.

  Note that terminology and filenames for these vary.  We want to
  provide Debian's users with consistency across packages, so you
  should rename the file(s) according to their contents.  Some
  language- or domain-specific packaging teams have more specific
  policies.  You should follow them, so that all packages in a
  particular domain are consistent.

  If information provided by upstream does not fit neatly into these
  categories, you should use your best judgement.  All documents that
  are useful to users should be in the binary package.

Ian.

Bug#459427: Patch seeking seconds on changelog vs. NEWS handling

[Sean Whitton]

Hello Bill,

On Fri 27 Jul 2018 at 12:31PM +0200, Bill Allombert wrote:

> I am fine with the removal of source-level changelogs, with the provisio
> that the concept of source-level changelog be clearly defined in policy.
> This needs to be worded carefully so that maintainers do not start
> removing user-oriented changelogs that happen to be named 'changelog',
> 'Changelog', etc. It is also not uncommon for packages to have both a
> user-oriented changelog and a NEWS file (which is basically the tl;dr of
> the user-level changelog).
>
> In that sense, the latest draft of Sean is a step in the right direction.
>
> I might be wrong, but I do not think the majority of upstream changelog
> are source-level changelog, except for GNU software. Changing debhelper
> not to install upstream changelog by default will likely create more
> bugs than it will fix.

After my patch Policy refers to "upstream release notes" and explicitly
says that those are user-oriented, and I think we can trust maintainers
to be able to identify those no matter what the file in which they are
contained is called.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#459427: Patch seeking seconds on changelog vs. NEWS handling

[Bill Allombert]

On Thu, Jul 26, 2018 at 08:09:48PM -0700, Russ Allbery wrote:
> Sean Whitton  writes:
> 
> > It's become clear that we do not have consensus on recommending that
> > only the release notes be installed, and not also the changelog.
> 
> I'm happy to see this go into Policy, but I find it unfortunate that we're
> unwilling to take a stance against this.  The source-level ChangeLog is
> essentially useless in Debian binary packages, and I've seen packages
> waste megabytes (compressed!) of space on it.  I'm installing it in one of
> my own packages because I felt an obligation to do so because Policy said
> I should, and I'm very happy to remove it.

Hello Russ,

I am fine with the removal of source-level changelogs, with the provisio
that the concept of source-level changelog be clearly defined in policy.
This needs to be worded carefully so that maintainers do not start
removing user-oriented changelogs that happen to be named 'changelog',
'Changelog', etc. It is also not uncommon for packages to have both a
user-oriented changelog and a NEWS file (which is basically the tl;dr of
the user-level changelog).

In that sense, the latest draft of Sean is a step in the right direction.

I might be wrong, but I do not think the majority of upstream changelog
are source-level changelog, except for GNU software. Changing debhelper
not to install upstream changelog by default will likely create more
bugs than it will fix.

Cheers,
-- 
Bill. 

Imagine a large red swirl here. 

Bug#459427: Patch seeking seconds on changelog vs. NEWS handling

[David Bremner]

Sean Whitton  writes:

>
> diff --git a/policy/ch-docs.rst b/policy/ch-docs.rst
> index 1de221f..e990f34 100644
> --- a/policy/ch-docs.rst
> +++ b/policy/ch-docs.rst
> @@ -255,32 +255,45 @@ files may be installed into ``/usr/share/doc/package``.
>  
>  .. _s-changelogs:
>  
> -Changelog files
> 
> +Changelog files and release notes
> +-
>  
>  Packages that are not Debian-native must contain a compressed copy of
>  the ``debian/changelog`` file from the Debian source tree in
>  ``/usr/share/doc/package`` with the name ``changelog.Debian.gz``.
>  
> -If an upstream changelog is available, it should be accessible as
> -``/usr/share/doc/package/changelog.gz`` in plain text. If the upstream
> -changelog is distributed in HTML, it should be made available in that
> -form as ``/usr/share/doc/package/changelog.html.gz`` and a plain text
> -``changelog.gz`` should be generated from it using, for example,
> -``lynx -dump -nolist``. 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
> +If an upstream release notes file is available, containing a summary
> +of changes between upstream releases intended for end users of the
> +package and often called ``NEWS``, it should be accessible as
> +``/usr/share/doc/package/NEWS.gz``.  An older practice of installing
> +the upstream release notes as ``/usr/share/doc/package/changelog.gz``
> +is permitted but deprecated.
> +
> +If there is an upstream changelog available, it may be made available
> +as ``/usr/share/doc/package/changelog.gz``.
> +
> +If either of these files are distributed in HTML, they should be made
> +available at ``/usr/share/doc/package/NEWS.html.gz`` and
> +``/usr/share/doc/package/changelog.html.gz`` respectively, and plain
> +text versions ``NEWS.gz`` and ``changelog.gz`` should be generated
> +from them, using, for example, ``lynx -dump -nolist``.
> +
> +If the upstream release notes or changelog 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.  [#]_
>  
>  All of these files should be installed compressed using ``gzip -9``, as
>  they will become large with time even if they start out small.
>  
> -If the package has only one changelog which is used both as the Debian
> -changelog and the upstream one because there is no separate upstream
> -maintainer then that changelog should usually be installed as
> -``/usr/share/doc/package/changelog.gz``; if there is a separate upstream
> -maintainer, but no upstream changelog, then the Debian changelog should
> -still be called ``changelog.Debian.gz``.
> +If the package has only one file which is used both as the Debian
> +changelog and the upstream release notes or changelog, because there
> +is no separate upstream maintainer, then that file should usually be
> +installed as ``/usr/share/doc/package/NEWS.gz`` or
> +``/usr/share/doc/package/changelog.gz`` (depending on whether the file
> +is release notes or a changelog); if there is a separate upstream
> +maintainer, but no upstream release notes or changelog, then the
> +Debian changelog should still be called ``changelog.Debian.gz``.
>  
>  For details about the format and contents of the Debian changelog file,
>  please see :ref:`s-dpkgchangelog`.
>

seconded

d

Bug#459427: Patch seeking seconds on changelog vs. NEWS handling

[Russ Allbery]

Sean Whitton  writes:

> It's become clear that we do not have consensus on recommending that
> only the release notes be installed, and not also the changelog.

I'm happy to see this go into Policy, but I find it unfortunate that we're
unwilling to take a stance against this.  The source-level ChangeLog is
essentially useless in Debian binary packages, and I've seen packages
waste megabytes (compressed!) of space on it.  I'm installing it in one of
my own packages because I felt an obligation to do so because Policy said
I should, and I'm very happy to remove it.

I second this patch, though, as a step forward and a way to resolve this
long-standing bug, so at least we can start standardizing on NEWS.gz as
the actually useful file and let people start retraining their finger
memory.  And this new text makes it clear that it's optional to install
the ChangeLog file, which is the other outcome that I wanted.

-- 
Russ Allbery (r...@debian.org)   

Bug#459427: Patch seeking seconds on changelog vs. NEWS handling

[Simon McVittie]

On Wed, 25 Jul 2018 at 20:57:41 -0700, Jonathan Nieder wrote:
> a) The work must carry prominent notices stating that you modified
>it, and giving a relevant date.

I don't think this is normally interpreted as requiring that *all*
modifications be listed, only that the existence of modifications is
obvious, or (to borrow wording from another popular license) the software
is not misrepresented as being the unmodified original source. Remember
that when the GPL was written, the expectation was that people would
receive Free Software on tapes or similar and would not be able to apply
the now-more-pragmatic policy of "if you want upstream's unmodified
version of GNU Hello, go and download it from GNU".

Debian packages have a Debian changelog and (when the source package
is included, without which we are not GPL-compliant anyway) a Debian
diff/tar, so there is certainly a prominent notice that we have modified
it. I am not a lawyer, but I believe this is enough for the letter and
spirit of the license: it tells a user "if you are looking for an
unmodified GNU Hello, this is not it".

smcv

Bug#459427: Patch seeking seconds on changelog vs. NEWS handling

[Holger Levsen]

On Thu, Jul 26, 2018 at 01:05:16PM +0800, Sean Whitton wrote:
> diff --git a/policy/ch-docs.rst b/policy/ch-docs.rst
> index 1de221f..e990f34 100644
> --- a/policy/ch-docs.rst
> +++ b/policy/ch-docs.rst
> @@ -255,32 +255,45 @@ files may be installed into ``/usr/share/doc/package``.
>  
>  .. _s-changelogs:
>  
> -Changelog files
> 
> +Changelog files and release notes
> +-
>  
>  Packages that are not Debian-native must contain a compressed copy of
>  the ``debian/changelog`` file from the Debian source tree in
>  ``/usr/share/doc/package`` with the name ``changelog.Debian.gz``.
>  
> -If an upstream changelog is available, it should be accessible as
> -``/usr/share/doc/package/changelog.gz`` in plain text. If the upstream
> -changelog is distributed in HTML, it should be made available in that
> -form as ``/usr/share/doc/package/changelog.html.gz`` and a plain text
> -``changelog.gz`` should be generated from it using, for example,
> -``lynx -dump -nolist``. 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
> +If an upstream release notes file is available, containing a summary
> +of changes between upstream releases intended for end users of the
> +package and often called ``NEWS``, it should be accessible as
> +``/usr/share/doc/package/NEWS.gz``.  An older practice of installing
> +the upstream release notes as ``/usr/share/doc/package/changelog.gz``
> +is permitted but deprecated.
> +
> +If there is an upstream changelog available, it may be made available
> +as ``/usr/share/doc/package/changelog.gz``.
> +
> +If either of these files are distributed in HTML, they should be made
> +available at ``/usr/share/doc/package/NEWS.html.gz`` and
> +``/usr/share/doc/package/changelog.html.gz`` respectively, and plain
> +text versions ``NEWS.gz`` and ``changelog.gz`` should be generated
> +from them, using, for example, ``lynx -dump -nolist``.
> +
> +If the upstream release notes or changelog 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.  [#]_
>  
>  All of these files should be installed compressed using ``gzip -9``, as
>  they will become large with time even if they start out small.
>  
> -If the package has only one changelog which is used both as the Debian
> -changelog and the upstream one because there is no separate upstream
> -maintainer then that changelog should usually be installed as
> -``/usr/share/doc/package/changelog.gz``; if there is a separate upstream
> -maintainer, but no upstream changelog, then the Debian changelog should
> -still be called ``changelog.Debian.gz``.
> +If the package has only one file which is used both as the Debian
> +changelog and the upstream release notes or changelog, because there
> +is no separate upstream maintainer, then that file should usually be
> +installed as ``/usr/share/doc/package/NEWS.gz`` or
> +``/usr/share/doc/package/changelog.gz`` (depending on whether the file
> +is release notes or a changelog); if there is a separate upstream
> +maintainer, but no upstream release notes or changelog, then the
> +Debian changelog should still be called ``changelog.Debian.gz``.

seconded.

(though personally I would prefer not to save a few bytes and not gzip
those files, but meh, thats another topic :)


-- 
cheers,
Holger


signature.asc
Description: PGP signature

Bug#459427: Patch seeking seconds on changelog vs. NEWS handling

[Sean Whitton]

[if you were CCed on this e-mail: this was because you seconded a
previous version of the patch which included a recommendation which I
have now dropped, and I hope you'll second the revised patch, further
down this e-mail]

Hello Jonathan,

On Wed 25 Jul 2018 at 08:57PM -0700, Jonathan Nieder wrote:

> Sean Whitton wrote:
>> On Wed 25 Jul 2018 at 07:01PM -0700, Jonathan Nieder wrote:
>
>>> I share gregor's discomfort: I don't think we've thought this through.
>>
>> I too want Policy to be as correct as possible, but this bug has been
>> open for ten years and one thing upon which there is certainly consensus
>> is that the current text is not satisfactory.  We should not let the
>> perfect be the enemy of the good, at least in this case.
>
> *puzzled* I am not asking for Policy to be more correct.  I'm asking
> for it to provide guidance that can help me with my own packages.
>
> I'm providing the data point that for me, the proposed patch to this bug
> does not work at all.  It is way too restrictive, and the argument being
> presented in favor of it is that I am allowed to ignore it.  This
> isn't about the perfect being the enemy of the good.  This is about
> wanting Policy to help me at all.
>
> Your response also feels dismissive.  I've tried to be very concrete
> in the input I provide here and I am wondering if this is appreciated
> at all or if you consider my contributions to be a nuisance.

Sorry about this.  I thought that your e-mail was more tangential than
it in fact is.  This misunderstanding on my part was why I wrote an
overly brief reply.  Let me try to do better in this e-mail.

> In that case, why don't we remove the requirement altogether?

It's become clear that we do not have consensus on recommending that
only the release notes be installed, and not also the changelog.  And
you have pointed out, importantly, that whether or not we can make such
a recommendation has implications with regard to licensing.  The issue
is much more subtle than I had thought.

We do have consensus on the rest of my patch, so far as I can tell (I
don't think you or Bill or Gregor has raised any problems with it, aside
from doubting whether we have consensus on the choice of naming).  And
further, ISTM that my patch is a decent basis upon which to have a
discussion of whether and what we should recommend be installed and not
installed.

So what I now seek seconds for is the following.  If someone would like
to drive the inclusion of a replacement for the text I've dropped, that
should be a new bug, with a clear statement of what is to be
accomplished.

diff --git a/policy/ch-docs.rst b/policy/ch-docs.rst
index 1de221f..e990f34 100644
--- a/policy/ch-docs.rst
+++ b/policy/ch-docs.rst
@@ -255,32 +255,45 @@ files may be installed into ``/usr/share/doc/package``.
 
 .. _s-changelogs:
 
-Changelog files

+Changelog files and release notes
+-
 
 Packages that are not Debian-native must contain a compressed copy of
 the ``debian/changelog`` file from the Debian source tree in
 ``/usr/share/doc/package`` with the name ``changelog.Debian.gz``.
 
-If an upstream changelog is available, it should be accessible as
-``/usr/share/doc/package/changelog.gz`` in plain text. If the upstream
-changelog is distributed in HTML, it should be made available in that
-form as ``/usr/share/doc/package/changelog.html.gz`` and a plain text
-``changelog.gz`` should be generated from it using, for example,
-``lynx -dump -nolist``. 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
+If an upstream release notes file is available, containing a summary
+of changes between upstream releases intended for end users of the
+package and often called ``NEWS``, it should be accessible as
+``/usr/share/doc/package/NEWS.gz``.  An older practice of installing
+the upstream release notes as ``/usr/share/doc/package/changelog.gz``
+is permitted but deprecated.
+
+If there is an upstream changelog available, it may be made available
+as ``/usr/share/doc/package/changelog.gz``.
+
+If either of these files are distributed in HTML, they should be made
+available at ``/usr/share/doc/package/NEWS.html.gz`` and
+``/usr/share/doc/package/changelog.html.gz`` respectively, and plain
+text versions ``NEWS.gz`` and ``changelog.gz`` should be generated
+from them, using, for example, ``lynx -dump -nolist``.
+
+If the upstream release notes or changelog 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.  [#]_
 
 All of these files should be installed compressed using ``gzip -9``, as
 they will become large with time even if they start out small.
 
-If the package has only one changelog which is used both as the Debian
-changelog and the upstream one because 

Bug#459427: Patch seeking seconds on changelog vs. NEWS handling

[Jonathan Nieder]

Sean Whitton wrote:
> On Wed 25 Jul 2018 at 07:01PM -0700, Jonathan Nieder wrote:

>> I share gregor's discomfort: I don't think we've thought this through.
>
> I too want Policy to be as correct as possible, but this bug has been
> open for ten years and one thing upon which there is certainly consensus
> is that the current text is not satisfactory.  We should not let the
> perfect be the enemy of the good, at least in this case.

*puzzled* I am not asking for Policy to be more correct.  I'm asking
for it to provide guidance that can help me with my own packages.

I'm providing the data point that for me, the proposed patch to this bug
does not work at all.  It is way too restrictive, and the argument being
presented in favor of it is that I am allowed to ignore it.  This
isn't about the perfect being the enemy of the good.  This is about
wanting Policy to help me at all.

Your response also feels dismissive.  I've tried to be very concrete
in the input I provide here and I am wondering if this is appreciated
at all or if you consider my contributions to be a nuisance.

>> Can you summarize the goals for me?
>
> 1. Stop encouraging the installation of changelogs, which sometimes has
>the effect of causing our package maintainers to request such logs
>from upstream.  This is not a good use of anyone's time.

In that case, why don't we remove the requirement altogether?

That would be a simple change, and it would achieve the goal, if that
is our main goal.

> 2. Explicitly encourage installing release notes and have a sensible
>filename for them.

I don't see a need for policy to do the first of those two things.
Packagers already install release notes when available, without
requiring any nudge from policy.

As for a sensible filename, I don't see this conversation having
developed toward any consensus (unless changelog.gz is that filename).

[...]
>>  4. Some licenses require distributing source-level changelogs.
>
> Could you give me an example of such a license, please?

The GPL contains the following:

  5. Conveying Modified Source Versions.

  You may convey a work based on the Program, or the modifications to
  produce it from the Program, in the form of source code under the terms of
  section 4, provided that you also meet all of these conditions:

a) The work must carry prominent notices stating that you modified
   it, and giving a relevant date.
[...]
  6. Conveying Non-Source Forms.

  You may convey a covered work in object code form under the terms
  of sections 4 and 5, provided that you also [...]

If Debian modifies a package, we comply with this prominent notice
requirement using the Debian changelog.  If the immediate upstream of
Debian modifies a package, then we ought to indicate when the
immediate upstream has modified the code, and the upstream changelog
accomplishes that.

This isn't too unusual.  The Apache license also contains a similar
provision about indicating that files have been modified, for example.

[...]
>>  ii. We don't impose any requirement on filename other than that they
>>  go in /usr/share/doc//.
>
> I disagree.
>
> It is useful to be able to just type `zless
> /usr/share/doc/foo/known-filename` rather than having to look at the
> filenames and guess what they are.

How do you do that on existing packages?  This bug was opened because
there isn't a consistent practice.

>>  iii. We come up with what format requirements we want to impose on
>>   the changelogs, if any.
>
> This is far out of scope for this bug.

If we set the filename and want people to type zless, then we are
imposing a format requirement (gzip).

Hope that helps,
Jonathan

Bug#459427: Patch seeking seconds on changelog vs. NEWS handling

[Sean Whitton]

Hello,

On Wed 25 Jul 2018 at 07:01PM -0700, Jonathan Nieder wrote:

> I share gregor's discomfort: I don't think we've thought this through.

I too want Policy to be as correct as possible, but this bug has been
open for ten years and one thing upon which there is certainly consensus
is that the current text is not satisfactory.  We should not let the
perfect be the enemy of the good, at least in this case.

> Can you summarize the goals for me?

1. Stop encouraging the installation of changelogs, which sometimes has
   the effect of causing our package maintainers to request such logs
   from upstream.  This is not a good use of anyone's time.

2. Explicitly encourage installing release notes and have a sensible
   filename for them.

>  4. Some licenses require distributing source-level changelogs.

Could you give me an example of such a license, please?

>  ii. We don't impose any requirement on filename other than that they
>  go in /usr/share/doc//.

I disagree.

It is useful to be able to just type `zless
/usr/share/doc/foo/known-filename` rather than having to look at the
filenames and guess what they are.

>  iii. We come up with what format requirements we want to impose on
>   the changelogs, if any.

This is far out of scope for this bug.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#459427: Patch seeking seconds on changelog vs. NEWS handling

[Jonathan Nieder]

Hi,

Sean Whitton wrote:
> On Mon 23 Jul 2018 at 01:40PM +0200, gregor herrmann wrote:

>> Let me see if I got this right, and apply it to the typical pkg-perl
>> package:
>>
>> CPAN distributions usually contain no NEWS file, and do contain a
>> Changes/ChangeLog/... file which is "an upstream release notes file"
>> per the above definition (hand-written by the upstream maintainer,
>> targetted at end users). (Numbers in message #65 in this bug report.)
>>
>> Currently we (i.e. typically dh_installchangelogs) install this
>> Changes file as /usr/share/doc/package/changelog.gz. In the future
>> we'd need to install it as /usr/share/doc/package/NEWS.gz; or still
>> as changelog.gz if we can live with the deprecation (will this be
>> allowed "forever"?).
>
> Until we can remove the deprecation without making more than a handful
> of packages buggy.  So, probably not for a long time.

I share gregor's discomfort: I don't think we've thought this through.

Can you summarize the goals for me?  My understanding of the current
status is:

 1. Installing all of upstream's release notes and source-level
changelogs is allowed.  Many people want to install fewer.

 2. Sometimes upstream doesn't provide adequate release notes.

 3. Sometimes upstream provides sensible release notes, but not as part
of the source archive they distribute.

 4. Some licenses require distributing source-level changelogs.

 5. Policy 12.7, perhaps inspired in part by those licenses, describes
where the upstream changelog (without specifying which changelog is
meant) should be installed and requires that it be installed
there.  It also has some requirements about format, compression
level, and so on.

 6. No tools other than lint and humans' muscle memories rely on the
path it specifies.

Am I understanding correctly so far?

Given that background and my understanding of the goals, my proposal
would be

 i.  We come up with which changelogs we want to *require* shipping,
 if any.

 ii. We don't impose any requirement on filename other than that they
 go in /usr/share/doc//.

 iii. We come up with what format requirements we want to impose on
  the changelogs, if any.

And we should take (2), (3), (4), and (6) into account when doing so.
Also, if my assumptions missed some pieces, I'd like to see them
clarified explicitly to avoid working at cross-purposes.

Thanks,
Jonathan

Bug#459427: Patch seeking seconds on changelog vs. NEWS handling

[Sean Whitton]

Hello Bill,

On Mon 23 Jul 2018 at 12:29PM +0200, Bill Allombert wrote:

> The issue is that the recommendation does not include a rationale, and
> it seems to me the rationale is based on an implicit definition of
> changelog which is not communicated either (or more precisely, it is
> based on the undocumented assumption that if a package includes both a
> changelog and a NEWS, the changelog is a source-level one, which is not
> always the case).
>
> So the maintainer has no basis to decide whether to ignore the recommendation.
>
> So I would suggest policy to define precisely the kind of sourcelevel 
> changelog
> that is not useful to the binary package user and recommend not to
> include them, with a rationale.
>
> It is always better for policy to state its goal explicitely.

Thank you for the explanation.  I disagree, however, that Policy should
be completely explicit here.  What we are doing is making a
recommendation based on a division of these files into two classes.
However, since there are all sorts of different files that there could
be in upstream sources, package maintainers are going to have to make a
judgement about what kind of files they have on their hands.  It's still
useful to have it pointed out to them that changelogs are less useful
than release notes in most cases.

I've made the following change on my branch (that I do not believe
invalidates any seconds) in response to your feedbacK:

diff --git a/policy/ch-docs.rst b/policy/ch-docs.rst
index 1503ed8..46c51cf 100644
--- a/policy/ch-docs.rst
+++ b/policy/ch-docs.rst
@@ -273,7 +273,10 @@ If there is no release notes file available, but there is 
an upstream
 changelog, it should be accessible as
 ``/usr/share/doc/package/changelog.gz``.  If there are both upstream
 release notes and an upstream changelog available, it is recommended
-to install the former but not the latter.
+to install the former but not the latter.  This recommendation applies
+when the upstream changelog would not be useful without the full
+upstream source, and so not useful in the binary package, but only in
+the source package.

 If either of these files are distributed in HTML, they should be made
 available at ``/usr/share/doc/package/NEWS.html.gz`` and

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#459427: Patch seeking seconds on changelog vs. NEWS handling

[Sean Whitton]

Hello gregor,

On Mon 23 Jul 2018 at 01:40PM +0200, gregor herrmann wrote:

> Let me see if I got this right, and apply it to the typical pkg-perl
> package:
>
> CPAN distributions usually contain no NEWS file, and do contain a
> Changes/ChangeLog/... file which is "an upstream release notes file"
> per the above definition (hand-written by the upstream maintainer,
> targetted at end users). (Numbers in message #65 in this bug report.)
>
> Currently we (i.e. typically dh_installchangelogs) install this
> Changes file as /usr/share/doc/package/changelog.gz. In the future
> we'd need to install it as /usr/share/doc/package/NEWS.gz; or still
> as changelog.gz if we can live with the deprecation (will this be
> allowed "forever"?).

Until we can remove the deprecation without making more than a handful
of packages buggy.  So, probably not for a long time.

> Did I get this right so far?

Yes.

> As written in message #140 in December, I still think we have two
> questions: which kind of files to install, and under which names.
> I think there's consensus for the first one, and this is expressed
> well in this patch. As for the second one, I have to admit that (if
> I'm reading the patch correctly) I'm still not happy of this forced
> rename of (CPAN) ChangeLogs to (GNU) NEWS.gz ...

Well, it is more like (CPAN) ChangeLogs to (Debian) NEWS.gz :)

I don't think it's right to view this as a forced rename, because of the
deprecation.  At least with this patch, there is no time limit.  We're
just stating that the newer practice is better.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#459427: Patch seeking seconds on changelog vs. NEWS handling

[gregor herrmann]

On Sun, 22 Jul 2018 11:35:48 +0800, Sean Whitton wrote:

> > +If an upstream release notes file is available, containing a summary
> > +of changes between upstream releases intended for end users of the
> > +package and often called ``NEWS``, it should be accessible as
> > +``/usr/share/doc/package/NEWS.gz``.  An older practice of installing
> > +the upstream release notes as ``/usr/share/doc/package/changelog.gz``
> > +is permitted but deprecated.
> > +
> > +If there is no release notes file available, but there is an upstream
> > +changelog, it should be accessible as
> > +``/usr/share/doc/package/changelog.gz``.  If there are both upstream
> > +release notes and an upstream changelog available, it is recommended
> > +to install the former but not the latter.

Let me see if I got this right, and apply it to the typical pkg-perl
package:

CPAN distributions usually contain no NEWS file, and do contain a
Changes/ChangeLog/... file which is "an upstream release notes file"
per the above definition (hand-written by the upstream maintainer,
targetted at end users). (Numbers in message #65 in this bug report.)

Currently we (i.e. typically dh_installchangelogs) install this
Changes file as /usr/share/doc/package/changelog.gz. In the future
we'd need to install it as /usr/share/doc/package/NEWS.gz; or still
as changelog.gz if we can live with the deprecation (will this be
allowed "forever"?).

Did I get this right so far?

If we want to install it as NEWS.gz we either have a tremendous
amount of work or we can wait for dh_installchangelogs to grow some
magic to do it for us (pr provide patches of course :)). And then
probably everyone who knows CPAN habits and/or has used Debian in the
last 25 years will still be at least slightly confused.

If we continue to install it as changelog.gz we hit the "deprecated"
case, and we might confuse other users, who - as per the change above
- expect changelog.gz to be the source-level changelog.


As written in message #140 in December, I still think we have two
questions: which kind of files to install, and under which names.
I think there's consensus for the first one, and this is expressed
well in this patch. As for the second one, I have to admit that (if
I'm reading the patch correctly) I'm still not happy of this forced
rename of (CPAN) ChangeLogs to (GNU) NEWS.gz ...


Cheers,
gregor

-- 
 .''`.  https://info.comodo.priv.at -- Debian Developer https://www.debian.org
 : :' : OpenPGP fingerprint D1E1 316E 93A7 60A8 104D  85FA BB3A 6801 8649 AA06
 `. `'  Member VIBE!AT & SPI Inc. -- Supporter Free Software Foundation Europe
   `-   BOFH excuse #421:  Domain controller not responding 

Bug#459427: Patch seeking seconds on changelog vs. NEWS handling

[Bill Allombert]

On Mon, Jul 23, 2018 at 07:50:59AM +0800, Sean Whitton wrote:
> Hello Bill,
> 
> On Sun 22 Jul 2018 at 07:45PM +0200, Bill Allombert wrote:
> 
> > I have to disagree with that recommendation. It all depends on how the
> > changelog is worded. Since we do not include a definition of changelog
> > and NEWS file, we cannot assume that one of them is useless without the
> > source code.
> >
> > For example pari-gp include both changelog.gz and NEW.gz and both are
> > potentially useful to users without a copy of the source.
> 
> I think we can rely on maintainer discretion to ignore Policy in cases
> like this.  Recommendations are weaker than "should" claims.

The issue is that the recommendation does not include a rationale, and
it seems to me the rationale is based on an implicit definition of
changelog which is not communicated either (or more precisely, it is
based on the undocumented assumption that if a package includes both a
changelog and a NEWS, the changelog is a source-level one, which is not
always the case).

So the maintainer has no basis to decide whether to ignore the recommendation.

So I would suggest policy to define precisely the kind of sourcelevel changelog
that is not useful to the binary package user and recommend not to
include them, with a rationale. 

It is always better for policy to state its goal explicitely.

Cheers,
-- 
Bill. 

Imagine a large red swirl here. 

Bug#459427: Patch seeking seconds on changelog vs. NEWS handling

[Sean Whitton]

Hello Bill,

On Sun 22 Jul 2018 at 07:45PM +0200, Bill Allombert wrote:

> I have to disagree with that recommendation. It all depends on how the
> changelog is worded. Since we do not include a definition of changelog
> and NEWS file, we cannot assume that one of them is useless without the
> source code.
>
> For example pari-gp include both changelog.gz and NEW.gz and both are
> potentially useful to users without a copy of the source.

I think we can rely on maintainer discretion to ignore Policy in cases
like this.  Recommendations are weaker than "should" claims.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#459427: Patch seeking seconds on changelog vs. NEWS handling

[Bill Allombert]

On Sun, Jul 22, 2018 at 11:35:48AM +0800, Sean Whitton wrote:
> control: tag -1 +patch
> 
> - I have chosen to include the recommendation not to install both the
>   changelog and the release notes if both are available.  I've done this
>   using the term 'recommended', which is the weakest requirement Policy
>   can impose; maintainer discretion is allowed.  We do seem to have
>   something of a consensus on this, and maintainers who do disagree can
>   ignore the recommendation.
> 
>   The argument for including the recommendation is that a changelog is
>   not very useful in a binary package, except as a fallback when no
>   release notes are available.  If you're going to dig into an upstream
>   changelog you will do so alongside a copy of the upstream source.  So
>   distributing the upstream changelog in only the source package, and
>   not the binary package(s), makes most sense.

I have to disagree with that recommendation. It all depends on how the
changelog is worded. Since we do not include a definition of changelog
and NEWS file, we cannot assume that one of them is useless without the
source code.

For example pari-gp include both changelog.gz and NEW.gz and both are
potentially useful to users without a copy of the source.

Cheers,
-- 
Bill. 

Imagine a large red swirl here. 


signature.asc
Description: Digital signature

Bug#459427: Patch seeking seconds on changelog vs. NEWS handling

[Yuri D'Elia]

On Sun, Jul 22 2018, Sean Whitton wrote:
>   The argument for including the recommendation is that a changelog is
>   not very useful in a binary package, except as a fallback when no
>   release notes are available.  If you're going to dig into an upstream
>   changelog you will do so alongside a copy of the upstream source.  So
>   distributing the upstream changelog in only the source package, and
>   not the binary package(s), makes most sense.

This is all very reasonable and I agree with the rationale.
I hope this can move forward.

Bug#459427: Patch seeking seconds on changelog vs. NEWS handling

[Andreas Henriksson]

On Sun, Jul 22, 2018 at 11:35:48AM +0800, Sean Whitton wrote:
> control: tag -1 +patch
> 
> Hello all,
[...]

Thanks for working on this and thanks for including your rationale
about the tradeoffs you had to make.

While I still retain my aging view on this which isn't perfectly
described by your proposal I'll myself take the advice from
'perfect is the enemy of good' and see that we would gain by having
these improvements in sooner rather than later.

Thus,

Seconded.

> > diff --git a/policy/ch-docs.rst b/policy/ch-docs.rst
> > index 1de221f..1503ed8 100644
> > --- a/policy/ch-docs.rst
> > +++ b/policy/ch-docs.rst
> > @@ -255,32 +255,48 @@ files may be installed into 
> > ``/usr/share/doc/package``.
> >
> >  .. _s-changelogs:
> >
> > -Changelog files
> > 
> > +Changelog files and release notes
> > +-
> >
> >  Packages that are not Debian-native must contain a compressed copy of
> >  the ``debian/changelog`` file from the Debian source tree in
> >  ``/usr/share/doc/package`` with the name ``changelog.Debian.gz``.
> >
> > -If an upstream changelog is available, it should be accessible as
> > -``/usr/share/doc/package/changelog.gz`` in plain text. If the upstream
> > -changelog is distributed in HTML, it should be made available in that
> > -form as ``/usr/share/doc/package/changelog.html.gz`` and a plain text
> > -``changelog.gz`` should be generated from it using, for example,
> > -``lynx -dump -nolist``. 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
> > +If an upstream release notes file is available, containing a summary
> > +of changes between upstream releases intended for end users of the
> > +package and often called ``NEWS``, it should be accessible as
> > +``/usr/share/doc/package/NEWS.gz``.  An older practice of installing
> > +the upstream release notes as ``/usr/share/doc/package/changelog.gz``
> > +is permitted but deprecated.
> > +
> > +If there is no release notes file available, but there is an upstream
> > +changelog, it should be accessible as
> > +``/usr/share/doc/package/changelog.gz``.  If there are both upstream
> > +release notes and an upstream changelog available, it is recommended
> > +to install the former but not the latter.
> > +
> > +If either of these files are distributed in HTML, they should be made
> > +available at ``/usr/share/doc/package/NEWS.html.gz`` and
> > +``/usr/share/doc/package/changelog.html.gz`` respectively, and plain
> > +text versions ``NEWS.gz`` and ``changelog.gz`` should be generated
> > +from them, using, for example, ``lynx -dump -nolist``.
> > +
> > +If the upstream release notes or changelog 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.  [#]_
> >
> >  All of these files should be installed compressed using ``gzip -9``, as
> >  they will become large with time even if they start out small.
> >
> > -If the package has only one changelog which is used both as the Debian
> > -changelog and the upstream one because there is no separate upstream
> > -maintainer then that changelog should usually be installed as
> > -``/usr/share/doc/package/changelog.gz``; if there is a separate upstream
> > -maintainer, but no upstream changelog, then the Debian changelog should
> > -still be called ``changelog.Debian.gz``.
> > +If the package has only one file which is used both as the Debian
> > +changelog and the upstream release notes or changelog, because there
> > +is no separate upstream maintainer, then that file should usually be
> > +installed as ``/usr/share/doc/package/NEWS.gz`` or
> > +``/usr/share/doc/package/changelog.gz`` (depending on whether the file
> > +is release notes or a changelog); if there is a separate upstream
> > +maintainer, but no upstream release notes or changelog, then the
> > +Debian changelog should still be called ``changelog.Debian.gz``.
> >
> >  For details about the format and contents of the Debian changelog file,
> >  please see :ref:`s-dpkgchangelog`.
> 
> -- 
> Sean Whitton

Bug#459427: Patch seeking seconds on changelog vs. NEWS handling

[Andrey Rahmatullin]

On Sun, Jul 22, 2018 at 11:35:48AM +0800, Sean Whitton wrote:
> > diff --git a/policy/ch-docs.rst b/policy/ch-docs.rst
> > index 1de221f..1503ed8 100644
> > --- a/policy/ch-docs.rst
> > +++ b/policy/ch-docs.rst
> > @@ -255,32 +255,48 @@ files may be installed into 
> > ``/usr/share/doc/package``.
> >
> >  .. _s-changelogs:
> >
> > -Changelog files
> > 
> > +Changelog files and release notes
> > +-
> >
> >  Packages that are not Debian-native must contain a compressed copy of
> >  the ``debian/changelog`` file from the Debian source tree in
> >  ``/usr/share/doc/package`` with the name ``changelog.Debian.gz``.
> >
> > -If an upstream changelog is available, it should be accessible as
> > -``/usr/share/doc/package/changelog.gz`` in plain text. If the upstream
> > -changelog is distributed in HTML, it should be made available in that
> > -form as ``/usr/share/doc/package/changelog.html.gz`` and a plain text
> > -``changelog.gz`` should be generated from it using, for example,
> > -``lynx -dump -nolist``. 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
> > +If an upstream release notes file is available, containing a summary
> > +of changes between upstream releases intended for end users of the
> > +package and often called ``NEWS``, it should be accessible as
> > +``/usr/share/doc/package/NEWS.gz``.  An older practice of installing
> > +the upstream release notes as ``/usr/share/doc/package/changelog.gz``
> > +is permitted but deprecated.
> > +
> > +If there is no release notes file available, but there is an upstream
> > +changelog, it should be accessible as
> > +``/usr/share/doc/package/changelog.gz``.  If there are both upstream
> > +release notes and an upstream changelog available, it is recommended
> > +to install the former but not the latter.
> > +
> > +If either of these files are distributed in HTML, they should be made
> > +available at ``/usr/share/doc/package/NEWS.html.gz`` and
> > +``/usr/share/doc/package/changelog.html.gz`` respectively, and plain
> > +text versions ``NEWS.gz`` and ``changelog.gz`` should be generated
> > +from them, using, for example, ``lynx -dump -nolist``.
> > +
> > +If the upstream release notes or changelog 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.  [#]_
> >
> >  All of these files should be installed compressed using ``gzip -9``, as
> >  they will become large with time even if they start out small.
> >
> > -If the package has only one changelog which is used both as the Debian
> > -changelog and the upstream one because there is no separate upstream
> > -maintainer then that changelog should usually be installed as
> > -``/usr/share/doc/package/changelog.gz``; if there is a separate upstream
> > -maintainer, but no upstream changelog, then the Debian changelog should
> > -still be called ``changelog.Debian.gz``.
> > +If the package has only one file which is used both as the Debian
> > +changelog and the upstream release notes or changelog, because there
> > +is no separate upstream maintainer, then that file should usually be
> > +installed as ``/usr/share/doc/package/NEWS.gz`` or
> > +``/usr/share/doc/package/changelog.gz`` (depending on whether the file
> > +is release notes or a changelog); if there is a separate upstream
> > +maintainer, but no upstream release notes or changelog, then the
> > +Debian changelog should still be called ``changelog.Debian.gz``.
> >
> >  For details about the format and contents of the Debian changelog file,
> >  please see :ref:`s-dpkgchangelog`.
Seconded.

-- 
WBR, wRAR


signature.asc
Description: PGP signature

Bug#459427: Patch seeking seconds on changelog vs. NEWS handling

[David Bremner]

Sean Whitton  writes:


>> diff --git a/policy/ch-docs.rst b/policy/ch-docs.rst
>> index 1de221f..1503ed8 100644
>> --- a/policy/ch-docs.rst
>> +++ b/policy/ch-docs.rst
>> @@ -255,32 +255,48 @@ files may be installed into ``/usr/share/doc/package``.
>>
>>  .. _s-changelogs:
>>
>> -Changelog files
>> 
>> +Changelog files and release notes
>> +-
>>
>>  Packages that are not Debian-native must contain a compressed copy of
>>  the ``debian/changelog`` file from the Debian source tree in
>>  ``/usr/share/doc/package`` with the name ``changelog.Debian.gz``.
>>
>> -If an upstream changelog is available, it should be accessible as
>> -``/usr/share/doc/package/changelog.gz`` in plain text. If the upstream
>> -changelog is distributed in HTML, it should be made available in that
>> -form as ``/usr/share/doc/package/changelog.html.gz`` and a plain text
>> -``changelog.gz`` should be generated from it using, for example,
>> -``lynx -dump -nolist``. 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
>> +If an upstream release notes file is available, containing a summary
>> +of changes between upstream releases intended for end users of the
>> +package and often called ``NEWS``, it should be accessible as
>> +``/usr/share/doc/package/NEWS.gz``.  An older practice of installing
>> +the upstream release notes as ``/usr/share/doc/package/changelog.gz``
>> +is permitted but deprecated.
>> +
>> +If there is no release notes file available, but there is an upstream
>> +changelog, it should be accessible as
>> +``/usr/share/doc/package/changelog.gz``.  If there are both upstream
>> +release notes and an upstream changelog available, it is recommended
>> +to install the former but not the latter.
>> +
>> +If either of these files are distributed in HTML, they should be made
>> +available at ``/usr/share/doc/package/NEWS.html.gz`` and
>> +``/usr/share/doc/package/changelog.html.gz`` respectively, and plain
>> +text versions ``NEWS.gz`` and ``changelog.gz`` should be generated
>> +from them, using, for example, ``lynx -dump -nolist``.
>> +
>> +If the upstream release notes or changelog 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.  [#]_
>>
>>  All of these files should be installed compressed using ``gzip -9``, as
>>  they will become large with time even if they start out small.
>>
>> -If the package has only one changelog which is used both as the Debian
>> -changelog and the upstream one because there is no separate upstream
>> -maintainer then that changelog should usually be installed as
>> -``/usr/share/doc/package/changelog.gz``; if there is a separate upstream
>> -maintainer, but no upstream changelog, then the Debian changelog should
>> -still be called ``changelog.Debian.gz``.
>> +If the package has only one file which is used both as the Debian
>> +changelog and the upstream release notes or changelog, because there
>> +is no separate upstream maintainer, then that file should usually be
>> +installed as ``/usr/share/doc/package/NEWS.gz`` or
>> +``/usr/share/doc/package/changelog.gz`` (depending on whether the file
>> +is release notes or a changelog); if there is a separate upstream
>> +maintainer, but no upstream release notes or changelog, then the
>> +Debian changelog should still be called ``changelog.Debian.gz``.
>>
>>  For details about the format and contents of the Debian changelog file,
>>  please see :ref:`s-dpkgchangelog`.

Seconded.

d


signature.asc
Description: PGP signature

Bug#459427: Patch seeking seconds on changelog vs. NEWS handling

[Sean Whitton]

control: tag -1 +patch

Hello all,

David Bremner and I took a look at this bug this morning at DebCamp
and I realised that I had been missing something (which Russ had
actually pointed out in an older message): lots of packages already
install a package's NEWS file as /usr/share/doc/foo/NEWS.gz.

This means that making this change would be documenting an existing
practice rather than having Policy drive a change to practice.  So
this removes the reasons that I had for thinking that debhelper should
change first.

We still have the problem that packages installing the NEWS file to
/usr/share/doc/foo/changelog.gz would be made buggy by a change that
simply required the NEWS file to be installed to
/usr/share/doc/foo/NEWS.gz.  But Bill pointed the way to a solution to
this: word Policy to allow both practices, but mark one as deprecated.

Looking through some of the messages to this bug, I think that the
following change is minimal enough to avoid too much controversy and
bikeshedding, so I'm seeking seconds for it.  Two further notes about my
patch:

- The patch defines what release notes are, but does not define what a
  changelog is.  This is not a regression, because Policy does not
  currently define what a changelog is.  And in fact the problem is
  hard, because the way that dev.ref. recommends we use debian/changelog
  makes it sound like it is a release notes file, not a changelog.  So I
  think we should put the issue aside as a separate change and not try
  to address it in this bug.

- I have chosen to include the recommendation not to install both the
  changelog and the release notes if both are available.  I've done this
  using the term 'recommended', which is the weakest requirement Policy
  can impose; maintainer discretion is allowed.  We do seem to have
  something of a consensus on this, and maintainers who do disagree can
  ignore the recommendation.

  The argument for including the recommendation is that a changelog is
  not very useful in a binary package, except as a fallback when no
  release notes are available.  If you're going to dig into an upstream
  changelog you will do so alongside a copy of the upstream source.  So
  distributing the upstream changelog in only the source package, and
  not the binary package(s), makes most sense.

> diff --git a/policy/ch-docs.rst b/policy/ch-docs.rst
> index 1de221f..1503ed8 100644
> --- a/policy/ch-docs.rst
> +++ b/policy/ch-docs.rst
> @@ -255,32 +255,48 @@ files may be installed into ``/usr/share/doc/package``.
>
>  .. _s-changelogs:
>
> -Changelog files
> 
> +Changelog files and release notes
> +-
>
>  Packages that are not Debian-native must contain a compressed copy of
>  the ``debian/changelog`` file from the Debian source tree in
>  ``/usr/share/doc/package`` with the name ``changelog.Debian.gz``.
>
> -If an upstream changelog is available, it should be accessible as
> -``/usr/share/doc/package/changelog.gz`` in plain text. If the upstream
> -changelog is distributed in HTML, it should be made available in that
> -form as ``/usr/share/doc/package/changelog.html.gz`` and a plain text
> -``changelog.gz`` should be generated from it using, for example,
> -``lynx -dump -nolist``. 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
> +If an upstream release notes file is available, containing a summary
> +of changes between upstream releases intended for end users of the
> +package and often called ``NEWS``, it should be accessible as
> +``/usr/share/doc/package/NEWS.gz``.  An older practice of installing
> +the upstream release notes as ``/usr/share/doc/package/changelog.gz``
> +is permitted but deprecated.
> +
> +If there is no release notes file available, but there is an upstream
> +changelog, it should be accessible as
> +``/usr/share/doc/package/changelog.gz``.  If there are both upstream
> +release notes and an upstream changelog available, it is recommended
> +to install the former but not the latter.
> +
> +If either of these files are distributed in HTML, they should be made
> +available at ``/usr/share/doc/package/NEWS.html.gz`` and
> +``/usr/share/doc/package/changelog.html.gz`` respectively, and plain
> +text versions ``NEWS.gz`` and ``changelog.gz`` should be generated
> +from them, using, for example, ``lynx -dump -nolist``.
> +
> +If the upstream release notes or changelog 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.  [#]_
>
>  All of these files should be installed compressed using ``gzip -9``, as
>  they will become large with time even if they start out small.
>
> -If the package has only one changelog which is used both as the Debian
> -changelog and the upstream one because there is no separate