New classes should have @since annotations, and classes not intended to be part
of the tomahawk "api" should be marked appropriately
------------------------------------------------------------------------------------------------------------------------------------
Key: TOMAHAWK-1324
URL: https://issues.apache.org/jira/browse/TOMAHAWK-1324
Project: MyFaces Tomahawk
Issue Type: Task
Reporter: Simon Kitching
Priority: Blocker
(1)
Adding @since annotations is standard practice. Any class added since 1.1.6
should have an @since 1.1.7 annotation on it. This includes all classes that
exist only in the tomahawk 1.2 branch.
(2)
Tomahawk has some classes that are published with the intention that users
invoke or subclass them; these are "the public api" of Tomahawk and that means
that they should not be modified in binary-incompatible ways in future
releases. Such classes need careful review of their apis as it is difficult to
fix them later.
Tomahawk also has classes which have the java qualifiers "public" or
"protected", but which really are not intended for use by the general public,
and which are not guaranteed to have stable apis. At the least we should mark
all such classes with a suitable javadoc comment. And ideally such classes
should have a name that starts with an underscore.
(3)
Classes that are part of the "stable public api" should not change between
releases.
The "clirr" tool can be used to generate a report that compares jars from two
releases and creates a report of the differences. This report can then be used
to help check 1,2 and 3 above.
Clirr is available as a maven report plugin, or as a standalone commandline
tool.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
