Thanks everyone for voting. With holiday coming up lets' keep this open for a few more days to give others a chance to vote if they want to- COB Tuesday May 26th.
Margot Aniruddh Dikhit wrote: > Margot > > I am more aligned with the minority opinion on this issue. > > -Aniruddh > > John Fischer wrote: >> Margot, >> >> Please put me down with the Minority group. >> >> Thanks, >> >> John >> >> >> Tom Childers wrote: >>> Agreed. I vote to approve with the TCR, and would support a TCA to >>> "document the interface classification in the native documentation". >>> -tdc >>> >>> >>> On May 20, 2009, at 3:53 PM, Margot Miller wrote: >>> >>>> I wouldn?t mind having a TCA to have teams document the >>>> interface classification in their native documentation. The >>>> only thing I disagree with is forcing teams to provide a man >>>> page if they don?t have the interface classification in their >>>> native documentation. >>>> >>>> Thanks >>>> Margot >>>> >>>> >>>> Mark A. Carlson wrote: >>>>> Deny - I'd change it to a TCA to "document the interface >>>>> classification >>>>> in the native documentation" (follow the outline in the minority >>>>> opinion). >>>>> >>>>> -- mark >>>>> >>>>> Margot Miller wrote: >>>>>> 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 >>>>>> _______________________________________________ >>>>>> opensolaris-arc mailing list >>>>>> opensolaris-arc at opensolaris.org >>>>> >>>>> -- >>>>> <http://www.sun.com> * Mark A. Carlson * >>>>> Sr. Architect >>>>> >>>>> *Systems Group* >>>>> Phone x69559 / 303-223-6139 >>>>> Email Mark.Carlson at Sun.COM >>>>> >>>> >>>> _______________________________________________ >>>> opensolaris-arc mailing list >>>> opensolaris-arc at opensolaris.org >>>> >>> >> >
