javadocs
Hi,
There is a growing tendency these last few years to remove -java-doc
packages as part of regular maintenance (including fixing builds or
updating to a new upstream release). As I could not find this issue
being discussed previously in this mailing list's archives, here we go.
Some figures: there are currently 337 -java-doc packages in bookworm,
264 in trixie, 272 in unstable, for a total of 348 unique names overall,
while I counted 1537 libsomething-java. This means that currently close
to 23% of packaged Java libraries provide a -java-doc package overall,
and that number is down to 18% currently in trixie.
Arguments in favor of their removal are so far:
- they often cause builds to break, especially with new releases of JDKs
or build tools
- they have a low popcon
- they can usually be downloaded from the upstream project or Maven
Central, or browsed online
- maintainer time would be better invested on other issues.
Tell me if I missed some.
I believe however that we should continue to provide -java-doc packages
for several reasons:
- Debian sometimes provides patched libraries that may behave slightly
differently than the upstream version
- not all projects reliably publish all versions of their developer
documentation on public repositories, and the documentation of some
older versions of libraries still packaged in Debian is not available on
the usual online services
- they are convenient for working offline (which also happens in
corporate settings, e.g. when deep inside a building where you won't
pick up your operator's network, there is no guest network, and the
corporate network has such an unfriendly and invasive policy that you
won't even try to connect to it)
- additional developer documentation (e.g. markdown files, reports) can
be provided with these package but are usually not bundled in upstream
javadoc archives
- they would remain available in Debian even if the upstream project
removed entirely its online presence for any reason
- as a matter of principle for completeness, downloadable developer
documentation being part of what's expected from a popular,
general-purpose, quality distribution such as Debian (even though there
is no such requirement in the Debian policy AIUI).
Popcon is IMO not a relevant metric to estimate the usefulness of
developer documentation packages (or, more generally, of packages that
would only be used by developers). Some -java-doc packages have a very
low popcon because the library package itself has a low popcon, and
developers (those that might need the documentation of a library) are a
tiny fraction anyway compared to regular users of a package (which
include developers that don't directly work on anything related to this
package). I also sampled a few other non-java library -doc packages and
they get similarly low popcon scores.
Build issues are a fact, but I think that there are ways to drastically
improve the situation, among other things by (automatically) testing new
JDK or build tool releases before discovering compatibility issues as
FTBFS bug reports pile up. A few other fixes in the toolchain are also
needed, and I'm planning to work on these (testing and toolchains) later
this year.
Now I understand why some maintainers would rather drop -java-doc
packages and I think that in the current situation it's fair to not make
it a priority to maintain them.
I'm thus proposing the following policy from now on, to be revisited
after the toolchain is fixed and we see how it goes with a few JDK and
build tool updates (so maybe 3 years from now, let's say 2028):
- maintainers may at their discretion drop -java-doc packages rather
than fix them when they encounter build issues
- other maintainers may (re-)introduce them at their discretion
- new library packages may introduce new -java-doc packages and that
"may" will revert to a "should" (as in the currently published Debian
policy for Java) once the toolchain is sufficiently improved.
What do you think of that?
Cheers,
--
Julien Plissonneau Duquène
Reply to: