Comment 0 for bug 1895799

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