Changes/OptionalJavadocs

Optional Javadocs

Summary

Make javadoc subpackages of Java packages optional in guidelines and communicate this change to users.

Owner

• Name: Stanislav Ochotnicky
• Email: sochotnicky@redhat.com
• Release notes owner:

Current status

• Targeted release: Fedora 21
• Last updated: 17th March 2014
• Tracker bug: <will be assigned by the Wrangler>

Detailed Description

With introduction of ARM as primary Fedora architecture and release of OpenJDK 8 it will become increasingly difficult to maintain javadoc subpackages in all Java packages. Initial testing showed 80% build failure rate due to OpenJDK 8 update. Additionally building javadocs is memory and CPU intensive and usually severely impacts build times (most on ARM architecture) for questionable benefit. Moreover our javadoc subpackages were never fully interconnected, mostly due to non-automated parts in generation. Work on improving javadoc generation is currently low-priority.

Making javadoc subpackages optional will enable packages with leaf packages (end user applications) or deprecated libraries with dead upstream which nobody should be developing against to opt-out of javadoc subpackage creation.

Benefit to Fedora

Easier and faster packaging, builds and introduction of new architectures.

Scope

• Proposal owners: Prepare new Java packaging guideline draft

• Other developers: (optionally) Remove their javadoc subpackages if it makes sense for their packages and make main package Obsolete them

• Release engineering: Nothing

• Policies and guidelines: New Packaging:Java guideline has to be prepared

Upgrade/compatibility impact

For packages where mainainter opted to remove javadoc subpackages, these will be removed during update of Fedora installations. We estimate this is going to impact *really* low number of users.

How To Test

This is mostly about guideline change and communicating this change to users. Testing can be done with repoquery and searching for obsoleted javadoc subpackages. For example:

$ repoquery --repoid=rawhide --whatobsoletes '*-javadoc'

User Experience

Not all java packages will have -javadoc subpackage available. Likely only small fraction of users are currently using them.

Dependencies

Partial dependency on Java 8 Change proposal but it can be implemented without it.

Contingency Plan

• Contingency mechanism: None needed, just a guideline and optional package change
• Contingency deadline: None
• Blocks release? No
• Blocks product? No

Documentation

https://lists.fedoraproject.org/pipermail/java-devel/2014-February/005133.html Current guideline change proposal

Release Notes

Javadoc subpackages have been made optional. If you need access to API documentation of Java libraries without javadoc subpackage try using upstream web pages which should be accessible at homepage URL of the project in question. You can query for the URL of installed package with rpm -qi <package> | grep '^URL'