Looking at the mail thread, it appears the votes are: "Majority" Margot (didn't see an actual vote from you) Tom
"Minority" Aniruddh John Mark Given this, I think we can consider the case approved and the opinion should switch the two opinions around. There should be the discussed TCA, but not the TCR. Can you please update the opinion and edit the IAM file? I will mark the other fast track cases closed approved. Thanks, -- mark Margot Miller wrote: > 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 >>>>> >>>> >>> >> > > _______________________________________________ > 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
