According to Fedora packaging guidelines, building Java documentation (-javadoc) packages is now optional. It was previously mandatory, then recommended, and is now left entirely to the maintainer's discretion. As the primary maintainer of many Java packages, I have decided to obsolete and remove Javadoc packages from all the packages I maintain. These changes will take effect in Fedora Rawhide (43) and later. I encourage others to consider doing the same. Why Remove Javadoc Packages? 1. Reduced maintenance burden Maintaining Javadoc packages isn't as simple as packaging documentation once and forgetting about it. Several issues make it time-consuming for maintainers. Javadoc generation often breaks with new JDK versions. Each major JDK update can introduce changes to the Javadoc tool (javadoc), leading to build failures. Maintainers must frequently patch Javadoc builds to maintain compatibility. By removing Javadoc packages, maintainers can focus on keeping core Java packages functional instead of spending time fixing documentation builds. 2. Reduced maintenance for javadoc-related tooling Many Javadoc builds depend on external tools (e.g., Maven plugins) that also require maintenance and updates. Updating a single Java library may also require updating its Javadoc dependencies. Removing Javadoc packages allows maintainers to retire unnecessary packages that exist only for building Javadocs. 3. Lower storage and bandwidth usage Javadoc packages take up considerable space because they contain thousands of interlinked HTML files, CSS, JavaScript, and image assets for styling, search indexes for fast lookups, and sometimes even embedded copies of external dependencies. For Fedora storing and distributing these extra files across mirrors is unnecessary when the same documentation is readily available online. Moreover, removal of more than a hundred of javadoc packages, each containing hundreds or thousands files, will result in non-negligible size reduction of repository metadata, particularly the file lists metadata. 4. Improved build reproducibility Fedora aims for reproducible builds, where compiling the same package on different systems should yield identical binaries. However, Javadoc generation makes this difficult due to various issues such timestamps embedded in generated files, non-deterministic ordering of elements, dependency on system fonts/external assets etc. Removing Javadoc packages enhances consistency and reproducibility across builds. 5. Availability of online alternatives Most Java libraries already publish documentation online. There exists javadoc.io service, which hosts Javadocs for most open-source projects. Developers typically already retrieve dependencies and documentation from repositories like Maven Central. Maintaining a separate Fedora-hosted copy is redundant when developers can access the latest online versions. 6. Eliminates privacy concerns Some Javadoc pages automatically load third-party resources, such as Google Fonts, Bootstrap CSS, JavaScript frameworks (e.g., jQuery). This raises privacy concerns because it can expose user behavior to external servers. In order to protect Fedora users from tracking them, Fedora maintainers take effort to patch out these resources. Removing Javadoc packages avoids these issues altogether. Conclusion While javadoc packages were useful in the past, the shift to online documentation and modern development tools has made them obsolete. Removing them from Fedora offers numerous benefits. For those who still need offline documentation, local javadoc generation remains an option. Given the high maintenance cost and diminishing benefits, I think it's time to retire Fedora's Javadoc packages. -- Mikolaj Izdebski -- _______________________________________________ devel mailing list -- devel@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe send an email to devel-leave@xxxxxxxxxxxxxxxxxxxxxxx Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/ List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/devel@xxxxxxxxxxxxxxxxxxxxxxx Do not reply to spam, report it: https://pagure.io/fedora-infrastructure/new_issue
