Mark A. Carlson wrote:
> Let's keep in mind that we are trying to document (in an easily
> accessible place) the
> interface classification of the OpenSolaris instance (not the Java
> interface across platforms).
> Given that we need to do this without massive patches to the upstream
> code, and that
> Java projects should use whatever native mechanism exists to document
> the classification
> across platforms, the OpenSolaris man page seems to be the best place.
I remain unconvinced that we (OpenSolaris) should even be concerned
about stability of Java APIs upon OpenSolaris. (With the possible
exception of APIs that are designed specifically to *support*
OpenSolaris itself.)
Do other members see value in having another layer of commitment and
review beyond whatever is already done as part of the Java community?
- Garrett
>
> -- mark
>
> Rick Matthews wrote:
>> I agree in principle with Jim's points. In particular,
>>> 1. Provides users stability and availability (taxonomy) information
>>> about jar file packages on Solaris/OpenSolaris not available anywhere
>>> else.
>> If ARCs are going to require this information, it should be
>> documented somewhere that a user
>> can find it a normal operating environment. Currently, I'd have to
>> agree this is man pages.
>>
>> I think a further point of this discussion is a need for ARCs to
>> adopt a consistent means of
>> doing so, and stick to it. In several of the cited cases with man
>> pages, the man pages were
>> produced as part of the Fast Track process. In the case of
>> LSARC/2009/262, it was questioned
>> why we would have man pages for jar/java release vehicles. That is
>> inconsistent, which is why
>> I believe Jim raised the issue.
>>
>> Toward that end, issues continue to be raised with jar/java FOSS
>> projects. There doesn't seem
>> to be a "checklist" of items needed for a FOSS jar project (and of
>> course, many checklists are
>> incomplete). As I recall, the following issues resulted from FOSS
>> cases delivering jar s:
>> 1) How to deliver javadocs to OpenSolaris (mostly due to web site
>> volume issues)
>> 2) Man pages for stability and taxonomy
>> 3) What portions need to have declared stability, etc. (like
>> package name)
>> 4) What JDK version(s)?
>> 5) Versioning of jar files
>>
>> Mark Martin brought up number 5 quite awhile ago. There was no
>> further action taken.
>> The jar files really seem to parallel C libraries, and should have a
>> best practice for versioning
>> similar to (or maybe expanded) "Library and Shared Object Requirements".
>>
>> IMHO, man page declaration of stability and taxonomy works. Let's
>> keep that until there
>> is a suitable "better way". Lloyd's method of documenting is a good
>> start, but we can't
>> hope to force external communities to use such a method, except by
>> general acceptance.
>> We could make it a best practice for non-FOSS jar deliverables that
>> are being ARCed.
>> This assumes Lloyd's proposal is sound, which I don't feel qualified
>> to have opinion.
>>
>> I think the ARCs need to look into these issues (as is being done),
>> and reasonable methods/
>> practices be established, and then those be consistently applied.
>> --
>> Rick
>>
>> On 05/13/09 13:30, Jim Walker wrote:
>>> For LSARC, PSARC and the opinion writer(s) to consider....
>>>
>>> Michael Kearney wrote:
>>>> 1. Lloyd, I like the idea of your annotation but have a couple of
>>>> concerns. - Would teams be expected to update third party, open
>>>> source jar files with the annotation?
>>>> - Would the ARC provide the common @Taxonomy annotation Java code?
>>>
>>> I have concerns too.
>>>
>>> In general, we will not be able to change FOSS code upstream like
>>> this. We normally try to do as little modification as possible (ie.
>>> just enough to get it to run well on Solaris/OpenSolaris). This
>>> is another reason why short man pages are being tacked on. Is it
>>> possible to tack on a page to the javadoc?
>>>
>>> I don't want to see big javadoc patches in the SFW consolidation that
>>> document detailed taxonomy information that we have to carry forever
>>> because they will never be accepted into the upstream community.
>>> Why would a FOSS project creating jar files even care about our
>>> taxonomy rules?
>>>
>>>> 2. What if the man page simple documented the stability at the
>>>> granularity of the jar file and
>>>> nothing else. Perhaps the man page could generically reference the
>>>> Javadoc?
>>>
>>> Not every jar file in /usr/share/lib/java has a man page, but
>>> that is the current practice, for the ones that do:
>>>
>>> $ man asm
>>> $ man mvel
>>> $ man janino
>>> $ man jettison
>>> $ man joda-time
>>> $ man jaxen-core
>>> $ man junit
>>> $ man ant (needs a more direct reference to javadoc)
>>> ...
>>>
>>> As I see it, having jar file man pages...
>>>
>>> 1. Provides users stability and availability (taxonomy) information
>>> about jar file packages on Solaris/OpenSolaris not available anywhere
>>> else.
>>> 2. Is pretty painless for project teams to produce and support.
>>> 3. Man pages do no harm, and I think users are already getting
>>> use to having them. Some information is better than no information.
>>> 4. Until there is a better way, man pages should be required for
>>> any new jar file submissions into Solaris/OpenSolaris. I thought
>>> this was already true.
>>> 5. Man pages are used by most Solaris/OpenSolaris packages.
>>> 6. I appreciate where Java developers are coming from, but "not
>>> standard
>>> practice for Java developers to look for man pages" alone, doesn't seem
>>> enough reason to stop man pages being delivered with jar file packages.
>>>
>>> We can't control how jar files are delivered or documented on
>>> windows or other environments, but we can on Solaris/OpenSolaris.
>>>
>>> BTW. ccing Norm (sfw c-team lead) since one of the requirements to
>>> integrate into sfw is a man page.
>>>
>>> Cheers,
>>> Jim
>>
>>
>
> --
> <http://www.sun.com> * Mark A. Carlson *
> Sr. Architect
>
> *Systems Group*
> Phone x69559 / 303-223-6139
> Email Mark.Carlson at Sun.COM
>
>
>
