On 04/09/10 04:01, Alan Wright wrote: > On 04/ 8/10 03:48 PM, Garrett D'Amore wrote: >> So while the list isn't *required*, it *is* desired (by me at least). > > I'm struggling to see the desire for this case to provide that > documentation. This case is documenting a change in smbstat output. > The fact that the kstat API is used internally is an existing > internal implementation detail, and ARC'ing details of the > internal implementation between smbsrv and smbstat for the purpose > of having a specification for something whose use is unsupported > seems strange.
I think it's really a nit (and much ado about nothing), but I agree with Garrett. The whole point of the "Private" ARC classification is that it encompasses things that people can *see* in some manner but that they should not *use*. Where we have adequate and reasonable means of hiding the interfaces (e.g., linker map files), they can become what's known as "Internal" interfaces and may need no special handling. Absent that (as is the case with kstats), ARC documentation marking them as some flavor of "Private" shows who should be using them. It's true that "Project Private" things needn't be disclosed. And it's true that changes to "Project Private" things don't need ARC review. So you can just drive on and ignore the issue. But the project team does get a benefit from going on-record to document their "Project Private" interfaces. If someone else -- completely unbeknowst to you -- wants to use them, then the ARC can warn him away appropriately and direct him to the proper alternative. This happens more often than you'd think. There are many layered "Explorer" types of tools around. You get at least that by merely listing them; something that should take no more than a few seconds' worth of effort. If you do more, and actually provide details, then more can be done. The ARC also serves as a repository of high-level design information. Long after you're gone, there may well be people who have to wander into this area. If there are copies of useful information in the ARC (often the _only_ source of information after a big RIF), then that future project team is in a better place, even if the information is somewhat stale. And it's often information that's useful to people exploring how to build higher-level tools. I think the ARC is effective only to the degree that project teams are engaged in the process and contribute well. If they hold back, the ARC is going to be less effective than it could be. There's nothing we can do to prevent secrecy but observe that the ARC is (or at least has been) an important commons. -- James Carlson 42.703N 71.076W <carls...@workingcode.com> _______________________________________________ opensolaris-arc mailing list opensolaris-arc@opensolaris.org
