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 >>> >> >
