Bug#459427: changelog vs. NEWS handling

[Adrian Bunk <bunk@debian.org>]

On Sun, Dec 03, 2017 at 05:24:09PM +0100, gregor herrmann wrote:
> On Thu, 30 Nov 2017 20:45:51 -0800, Russ Allbery wrote:
> 
> > I think
> > the most valuable starting point would to be to standardize on
> > /usr/share/doc/package/NEWS.gz for the human-readable summary and
> > explicitly say to never install that as
> > /usr/share/doc/package/changelog.gz.  
> 
> That would mean that we have to manually add something to d/rules for
> thousands of perl packages in order to make ChangeLog, Changes etc.
> getting installed as /usr/share/doc/package/NEWS.gz.
> (Unless dh_installchangelogs gets some logic to install ChangeLog,
> Changes etc. as NEWS.gz if there is no NEWS in the upstream tarball.
> But that might be confusing …)
> 
> On Fri, 01 Dec 2017 13:34:01 -0700, Sean Whitton wrote:
> 
> > We can at least make dh_installchangelogs capable of installing both
> > changelog.gz and NEWS.gz before we change Policy.  Otherwise, fixing the
> > minor bugs is significantly more annoying.
> 
> Ack, this would be a good start.

Policy should define the naming before dh_installchangelogs should 
change.

Related is also the question whether any change at all will be
done before debhelper compat 12 - with such a piecemeal approach
we risk fragmentation based on debhelper compat level used, with every 
new compat level installing different files in different locations.

This bug has already celebrated its 10th birthday.

IMHO the way forward is to find a consensus text for a policy change,
Cc debian-devel on the proposal, and if no objections are raised release 
a new policy with these changes.

If additionally installing NEWS turns out to be the only consensus 
change then let's do that in policy now and close the topic.

If there can be consensus on more, then let's do this now.

> > If we are going to add something that says that upstream NEWS/release
> > notes should also be installed, why not standardise on the location?  It
> > seems odd to have a standard location for upstream changelogs but not
> > for upstream NEWS/release notes.
> > 
> > Or perhaps we should drop the standard location for upstream changelogs.
>  
> Having some standardization makes it easier for both users and their
> tools to quickly find what they are looking for. But yeah, I think we
> have at least 2 problems in this area:
> - no single standard on the upstream side (c.f. the GNU style vs. the
>   CPAN style(s))
> - needed changes in our tooling (dh_installchangelogs)
> 
> And we have 2 questions to answer:
> 1) Which files to install?
> 2) Under what name?
> 
> What policy could say is:
> 1) - If there is a human-facing summary, install it.
>    - If there is a human-facing summary and a VCS-style log, install
>      the former but not the latter.
>    - If there is no human-facing summary but a a VCS-style log,
>      consider installing the latter.
>    (Without mentioning file names, or maybe as examples, as they are
>    not standardized).
> 2) Install NEWS as /usr/share/doc/package/NEWS.gz and /Change.*/i as
>    /usr/share/doc/package/changelog.gz if you install them.
>    (That's also something dh_installchangelogs could do easily.)

This sounds like a good suggestion to me and I'd be willing to make a 
policy proposal based on that, with a wording that the maintainer "may" 
install a VCS-style log even when a human-facing summary is present.

If anyone has objections to this proposal, please speak up.

Coordinating with Niels regarding how to synchronize policy and 
debhelper changes is something I'll do after we have agreement
how the end result should look like.

> Cheers,
> gregor

cu
Adrian

-- 

       "Is there not promise of rain?" Ling Tan asked suddenly out
        of the darkness. There had been need of rain for many days.
       "Only a promise," Lao Er said.
                                       Pearl S. Buck - Dragon Seed