Groups | Search | Server Info | Keyboard shortcuts | Login | Register

Groups > linux.debian.maint.java > #12928

javadocs

Show all headers | View raw

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

Back to linux.debian.maint.java | Previous | Next — Next in thread | Find similar

Thread

javadocs Julien Plissonneau Duquène <sre4ever@free.fr> - 2025-02-18 10:50 +0100
  Re: javadocs Emmanuel Bourg <ebourg@apache.org> - 2025-02-18 12:50 +0100
    Re: javadocs Julien Plissonneau Duquène <sre4ever@free.fr> - 2025-02-19 09:30 +0100
  Re: javadocs Julien Plissonneau Duquène <sre4ever@free.fr> - 2025-02-19 09:00 +0100
    Re: javadocs Julien Plissonneau Duquène <sre4ever@free.fr> - 2025-02-19 09:40 +0100

csiph-web