pkgstripfiles doesn't respect override_dh_installchangelogs targets

[Peter J. Mello]

During the course of preparing to satisfy an upstream RFP on the Debian BTS WNPP metapackage, I encountered some uncouth behavior on the part of pkgstripfiles, which is shipped by this package and almost entirely undocumented (no mention in the package description and no man page shipped).

As this is the first iteration of a Debian package it only has the single changelog entry, and so I decided to use an override_dh_installchangelogs target in debian/rules to cause dh to rename and compress the ChangeLog.md and include it with the other pieces of documentation. This decision is supported by Debian Policy Section 12, Subsection 7[1], added with Version 4.2.0 on August 2018. The target invoked dh_installchangelogs manually with the filename of the upstream changelog as the only argument and it performs as intended when called manually.

However when the full package build process is performed, the upstream changelog was not present in the built package. A review of the build log revealed that pkgstripfiles had removed it just prior to completion of the build. This is not a good outcome on several levels, among them:

  - As Ubuntu is a downstream fork, any packaging behavior which subverts published Debian Policy should behave as an "opt-in" function and should take care to announce itself even during scripted invocations so established workflows aren't cryptically subverted and cost users increased time spent simply to identify the culprit.
  - Documentation should exist to explain the behavior and the logic behind its inclusion in the packaging process, placed where users are most likely to look for it. In this case a man page at pkgstripfiles(1) would've been lovely, or even one for the entire package at pkgbinarymangler(8) seems warranted at a minimum. The fact that the other executables in the package and their configuration files are described briefly in the package description but this one was not felt like dirty pool.
  - The executable should have a HEREDOC to produce in response to invocation with a -h/--help flag explaining its usage. In a brief skim of its shell logic I saw no option parsing at all, which was a shame because I had no quarrel with its other behaviors during packaging and would've happily written another override target into debian/rules to allow it to remain in the dh sequence with a flag that deactivated only its internal 'clean_upstream_changelogs' function. That wasn't even possible from within the likewise undocumented .conf file it has in /etc/pkgbinarymangler. It seems logical that all the script's internal functions should have command line options that explicitly control their activation or lack thereof for single invocations, and they should all have counterparts in the .conf file to effect those changes to its behavior permanently.
  - Ideally it would have the necessary logic to parse the obvious constructs in debian/rules for override targets related to its internal functions and turn those functions off which might impede the maintainer's work without intervention.

This was experienced on a system running the Kubuntu 20.10 "Groovy Gorilla" development release.

Relevant package versions:
 * dpkg - 1.20.5ubuntu1
 * debhelper - 13.2ubuntu1
 * pkgbinarymangler - 146

[1]: https://www.debian.org/doc/debian-policy/ch-docs.html#changelog-files-and-release-notes

[Launchpad Janitor (janitor)]

Status changed to 'Confirmed' because the bug affects multiple users.

[Athos Ribeiro (athos-ribeiro)]

amavisd-new debian/rules calls override_dh_installchangelogs with the -k option to keep the original upstream changelog file name.

This results not only in the upstream changelog being removed, but in a broken symlink being shipped with the package.

# file /usr/share/doc/amavisd-new/RELEASE_NOTES.gz
/usr/share/doc/amavisd-new/RELEASE_NOTES.gz: broken symbolic link to changelog.gz

[Utkarsh Gupta (utkarsh)]

Hey,

As Athos stated, I can reproduce the same thing in the devel release as well and it seems that Debian sid isn't affected due to this. Adding sever-todo for someone from the Server team to take a look at this one.

[Christian Ehrhardt  (paelzer)]

IMHO this is not meant to be fixed in every package that uses dh_installchangelogs -k

This:
  https://codesearch.debian.net/search?q=dh_installchangelogs.*-k&literal=0
reports 317 affected packages.

Just picking one
libxml2 has
    dh_installchangelogs -k NEWS
And it became a broken symlink:
root@j:~# ls -laF /usr/share/doc/libxml2/NEWS.gz /usr/share/doc/libxml2/changelog.gz /usr/share/doc/libxml2/changelog.Debian.gz
ls: cannot access '/usr/share/doc/libxml2/changelog.gz': No such file or directory
lrwxrwxrwx 1 root root 12 Feb 9 04:39 /usr/share/doc/libxml2/NEWS.gz -> changelog.gz
-rw-r--r-- 1 root root 1550 Feb 9 04:39 /usr/share/doc/libxml2/changelog.Debian.gz

Same PKG in Debian
root@d10-sid:~# ls -laF /usr/share/doc/libxml2/NEWS.gz /usr/share/doc/libxml2/changelog.gz /usr/share/doc/libxml2/changelog.Debian.gz
lrwxrwxrwx 1 root root 12 Nov 17 19:27 /usr/share/doc/libxml2/NEWS.gz -> changelog.gz
-rw-r--r-- 1 root root 21856 Nov 17 19:27 /usr/share/doc/libxml2/changelog.Debian.gz
-rw-r--r-- 1 root root 49632 Oct 22 2019 /usr/share/doc/libxml2/changelog.gz

I'll bump the prio of this on the pkgbinarymangler side.
The earlier we fix this the more packages will be rebuilt anyway and fixed eventually.

[Adrien Nader (adrien)]

It looks like #1297025 might be a duplicate of this issue.