Bug#1067901: jh_installjavadoc: should not write duplicative doc-base files.

[James Addison]

Package: javahelper
Version: 0.79
Severity: normal
User: reproducible-builds at lists.alioth.debian.org
Usertags: fileordering
Control: affects -1 libpixels-java

Dear Maintainer,

I'm an occasional volunteer contributor to the Reproducible Builds[1] project,
and noticed that the 'libpixels-java' package, which build-depends on
javahelper (src:javatools) and uses jh_installjavadoc, failed[2] an automated
build test on the Reproducible Builds test infrastructure for Debian.

In particular, the /usr/share/doc-base/libpixels-java.libpixels-java file
varied between a control and experimental package build.

The cause seems to relate to logic that writes[3] a '$package.doc-base.javadoc'
file into the 'debian' directory during build.

In the case of libpixels-java, that template file is written alongside an
existing 'debian/doc-base' file[4] contained in the source package.  Both of
the files then contain an identical doc-id statement[5], and it's unpredictable
which of them will be read[6] from the directory by dh_installdocs - it depends
on the ordering returned by the filesystem.

If it seems like a reasonable solution to you, perhaps jh_installjavadoc could
be modified so that it does not write a templated doc-base file for a package
when it detects an existing doc-base file that contains the same doc-id?

Thank you,
James

[1] - https://reproducible-builds.org/

[2] - https://tests.reproducible-builds.org/debian/rb-pkg/unstable/amd64/diffoscope-results/libpixels-java.html

[3] - https://sources.debian.org/src/javatools/0.79/jh_installjavadoc/?hl=86#L105-L118

[4] - https://sources.debian.org/src/libpixels-java/2.1.3%2Bsvn.42-3/debian/doc-base/

[5] - https://sources.debian.org/src/libpixels-java/2.1.3%2Bsvn.42-3/debian/doc-base/#L1

[6] - https://sources.debian.org/src/debhelper/13.14.1/dh_installdocs/#L406