[Debian-med-packaging] Bug#922861: samtools: Outdated and missing documentation files

[Andreas Tille]

Control: tags -1 pending

Hi John,

thanks a lot for the proof reading of the Debian package content.
That's really appreciated.

On Thu, Feb 21, 2019 at 01:17:54PM +0000, John Marshall wrote:
> Package: samtools
> Version: 1.9-3
> 
> This package places the following in /usr/share/doc/samtools:
> 
> AUTHORS
> NEWS.Debian.gz
> README.Debian
> changelog.Debian.gz
> copyright
> examples/
> reference
> 
> AUTHORS comes from the upstream release.

Yes.  I think that's OK.

> NEWS.Debian.gz contains an ancient "samtools (1.3-1) unstable; urgency=medium" Debian changelog item.

Yes.  This is intended as well.  The file NEWS.Debian.gz is evaluated by
apt-listchanges[1] to inform local admins about changes that need to be
respected in a certain package version.  It should match the changelog
line of the corresponding Debian package.  If an admin installs samtools
1.3 or higher on top of say samtools 1.2 apt-listchanges will display
the according notes.  If an admin just has samtools 1.3 (or higher
installed) apt-listchanges will not install anything.  That means there
are no news since samtools 1.3 in terms of **packaging** - so this file
is correct.

> README.Debian contains out-of-date Debian-specific information that is now incorrect.

Thanks for spotting this.  I tried to address this issue in[2].

If you have extra comments how to deal with the scripts in misc please
let us know.  We would love to design the Debian package perfectly in
line with upstream plan how the software should be installed on user
machines.

> changelog.Debian.gz is an up-to-date Debian changelog.
> copyright is an up-to-date Debian summary of licensing.

These files are default in every Debian package.

> examples/ comes from the upstream release.

Its very usual to install examples provided by upstream as
extra user documentation.

> reference is an up-to-date Debian addition.

That's correct.  However, I have removed this piece of duplicated
information anyway.  We are maintaining this information now
consistently in all scientific packages in debian/upstream/metadata and
you can see that it is rendered for instance on our tasks page[3].
There you can see the citation as well as registry information.

> NEWS.Debian.gz should be replaced by an up-to-date copy of the upstream release's NEWS file. (The related htslib packages do this via override_dh_installchangelogs.)

That's a wrong interpretation of the NEWS.Debian.gz file as I tried to
explain above.  However, its probably a good idea to install your file
NEWS as upstream changelog which I did in Git now[4].
 
> README.Debian should be updated or removed.

See above / [2].
 
> The package is missing the upstream release's README file. It would be good to install this file, even though it doesn't currently contain a great deal of salient information. (The upstream release's INSTALL file is also missing, but that is of course appropriate for a binary package.)

Done in Git[5]
 
> (The related htslib Debian packages are also missing their upstream release README file.)
Done in Git[6]

Thanks a lot for your comments which are really appreciated

      Andreas.


[1] https://manpages.debian.org/testing/apt-listchanges/apt-listchanges.1.en.html
[2] https://salsa.debian.org/med-team/samtools/commit/770284c73cd785c17e1801ac2e07799c925cdfa0
[3] https://blends.debian.org/med/tasks/bio#samtools
[4] https://salsa.debian.org/med-team/samtools/commit/9587f1d14aa3a8ed385c72966c0ed5ec5870046f
[5] https://salsa.debian.org/med-team/samtools/commit/3c46ee230ac79c35af490627628ca4669e337148
[6] https://salsa.debian.org/med-team/htslib/commit/18fc49dd7454539a6276f75eb40775c96af37340
-- 
http://fam-tille.de