All,
I have included the minority opinion written by Mark Carlson.
We did in fact have quorum yesterday; our external member
was not listed as a full member.
In any case, due to the lack of perceived quorum yesterday,
please vote on this case.
Vote to approve the case as written (with the TCR)
Vote to deny
If we find we now have a majority denying the case because
they don?t agree with the TCR, then the TCR camp will
become the minority.
Thanks
Margot
microsystems Systems Architecture Committee
_________________________________________________________________
Subject: trove-2.0.4
Submitted by: Vivek Titamare
File: LSARC/2009/262/opinion.txt
Date: May, 2009
Committee: Margot Hackett Miller, Lloyd Chambers
Minority: Mark Carlson
Product Approval Committee:
Solaris PAC
solaris-pac-opinion at sun.com
1. Summary
This project is one of the Linux familiarity cases; this one provides
a library to do fast regular and primitive collections for
Java.
2. Decision & Precedence Information
The project is approved as specified in reference [1].
The project may be delivered in a minor release of Solaris.
3. Interfaces
Exported Interfaces:
__________________________________________________
| Interfaces Exported |
|____________ ______ |____________ __ __|____________|
|Interface | Classification | Comments|
|_______________ __|_________________|_____________|
| trove.jar | Uncommitted | |
|SUNWtrove | Uncommitted | |
|___________________|_________________|____________|
Imported Interfaces:
______________________________________________________________
| Interfaces Exported | |
|___________________|______________ __|________________________|
|Interface | Classification | Comments |
|_______________ __|_________________|________________________|
|
| SUNWj5dev | Committed | Java Development kit |
| SUNWj5rt | Committed | Java Runtime library |
| SUNWj6dev | Committed | Java Development kit |
| SUNWj6rt | Committed | Java Runtime library |
|___________________|_________________|________________________|
4. Opinion
During review, the only real issue raised was whether this team
should provide a man page in addition to the javadocs. The man
page would basically give a brief description of the jar file,
pointer to the javadocs, and state the interface stability of the jar file.
Discussion ensued whether it makes sense to ship a man page
with a jar file. Solaris developers expect man pages, but do
Java developers? Is it worth the extra work to provide a man page
and would Java developers even look for a man page.
It was noted that this is not standard practice as most Java developers
look
for java documentation via javadocs, not via man. However, others stated
that
having a minimal man page for a java jar file would allow the interface
classification to be visible to the end user and a few other ARC cases have
already shipped man pages for jar files.
There was discussion over the granularity of the jar file and does
it make sense to have an interface stability for the overall jar.
Currently,
java has Public, Package, and Protected. There was debate as to
whether that conveys enough of the stability of the jar and its methods
to the
developer.
With all the FOSS that is being delivered into Solaris, projects are
delivering in their native, natural form. This includes man pages, texinfo,
html, and javadoc. So the problem isn't just with javadocs and jar files.
There is quite a bit of FOSS out there with no interface stability
in the external Sun documentation. This is not a problem for Sun
project teams as they can always look at the interface tables in
the ARC tables to determine stability level.
Asking all java project teams to ship a man page in addition to javadocs
doesn?t
seem like the right solution and having some teams ship a man page
and others not, does not provide consistency.
There needs to more discussion to determine if it is critical that the
ARC stability
level be communicated to the Solaris end user for all the FOSS software
that is being delivered. If so, a comprehensive solution needs to be
formulated, whether it is a CLI, a man page, annotation embedded in the
Javadocs
(which will work for Sun products but you cant force that upstream).
This is not being addressed in this case. Project teams can continue
to ship documentation in their ?natural?form and if there is some
stability suggested in that documentation that is fine.
Up until now, most projects have not shipped man pages with jar
files. This doesn?t seem to have been written down anywhere. With
this case, we would like to make it explicit to not deliver man pages
with jar files. This is setting precedent of ?do not ship man pages
with jar files.? This resulted in the below TCR.
5. Minority Opinion(s)
Background
It is not typical for programmers working with non C/C++/Assembler
files, such as Java Jar files, to determine the
Exported Interface stability level using the man command. Java
programmers depend on Javadoc, Python programmers
depend on pydoc and so forth to document interfaces and the
stability would best be indicated there.
Approval of OpenSolaris projects have been inconsistent in
preferring man pages or native documentation. This opinion seeks
to clarify the issue and define a policy for all such cases going
forward.
Best Practice
Case A - Sun Developed Components
1) Sun project team developing a Jar file shall document the
ARC interface classification in the native documentation. (i.e.
Javadocs)
Case B - Components imported from external OSS Communities
1) The OSS Community documents the interface classification in
their native documentation
a) OpenSolaris project team agrees with the classification
and supports it
- Javadoc or other native documentation required
(unchanged)
- No man page shall be allowed
b) OpenSolaris project team disagrees with the classification
- Javadoc or native documentation required, but
project team must change the OSS documentation
to match the project team's classification
- No man page shall be allowed
2) OSS Community does not document interface classification in
their native documentation
a) OpenSolaris project team is strongly encouraged to
update the native documentation to reflect the OpenSolaris project
team
classification.
- Changed Javadoc or other native documentation required
- No man page shall be allowed
b) OpenSolaris project team cannot support deltas to the
native documentation
- Unchanged Javadoc or other native documentation required
- A man page shall be provided
6. Advisory Information
None.
7. Appendices
7.1. Appendix A: Technical Changes Required
Do not ship man pages with Java jar files
7.2. Appendix B: Technical Changes Advised
None.
7.3. Appendix C: Reference Material
Unless stated otherwise, path names are relative to the case
directory LSARC/2009/262
1) Project Proposal file:
LSARC/2009/262 Copyright 2009 Sun Microsystems
