Please see comments embedded below. Michael Kearney wrote: > See comments inline: > > margot wrote: >> Hey All, >> >> Here is the draft opinion. >> >> Please review/comment. >> Thanks >> Margot >> >> ****************** >> >> >> sun >> 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. Does that convey 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). > Shouldn't the discussion take place before rendering an opinion and > setting a precedence? I think we identified the problem but this case can not solve that. For this case, the issue has to do with projects shipping man pages with jars. The precedence is do not ship man pages with jar files. We still need to figure out how to communicate stability level to customers on all FOSS. But that? not this case. >> >> 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. > So, for Java projects (and all other types of projects where the > "natural" documentation doesn't > include a man page), no documentation of the interface stability is > allowed? > We really should set the precedent for all types of projects, > otherwise we'll just be back here next > week to discuss Python, etc.
I did not mean to imply that. The only thing here is- do not ship a man page. If the stability level is in the docs, like the AppServer is proposing with annotations, they can ship that. What we did say at the meeting is that project teams do not have to modify the ?natural? docs to include stability level. I will add this clarification to the opinion. Thanks Margot >> >> 5. Minority Opinion(s) >> >> Mark Carlson providing text >> >> 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 >> >
