Michael Kearney writes: > > 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?
Yep; agreed. For what it's worth, I would vote for using native documentation and native stability indications where feasible, and adding our own notations only when the community lacks sufficient information. I don't think it makes sense to force communities that have their own stability traditions to conform to our mold, provided that the "communities" include those Sun customers who would also receive this software. One of the high level goals of this architecture process is to make sure that dependencies are documented, and expectations are understood both by suppliers and consumers. As long as that goal is reached in a consistent and unsurprising way, I don't really care whether it's done by way of 'man', 'pydoc', 'javadoc', or 'whatsupdoc.' The only time it matters is when crossing worlds. If users can depend on both Java and Python supplied interfaces (for instance), then they would need a decoder ring to understand what each one provides, and that might well lead to mistakes. Thus, the boundaries for these native stability interfaces need to be crystal clear. (That is to say: external protocols, file formats, command lines, and visible-to-those-outside-the-domain programming interfaces are likely all things that cannot be documented properly using native stability levels.) > > 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 had thought that the actual vote in LSARC was 2-to-1 to allow man pages as an option. But I agree that it does need to be consistent so that we don't have to have this debate every few months. -- James Carlson, Solaris Networking <james.d.carlson at sun.com> Sun Microsystems / 35 Network Drive 71.232W Vox +1 781 442 2084 MS UBUR02-212 / Burlington MA 01803-2757 42.496N Fax +1 781 442 1677
