On Fri, Apr 9, 2010 at 7:51 AM, James Carlson <[email protected]> wrote: > 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 <[email protected]>
Exactly, and with kstats (at least), they are going to be used regardless (witness net-snmp -- I'm pretty sure every kstat it consumes -- which is a lot -- are all classified as private) since often there is no alternative. Having some documentation gives those of aren't Sun employees a starting point to try to do the right thing (i.e. find the right people, talk about raising the classification as needed for a project, etc.) instead of just giving up. _______________________________________________ opensolaris-arc mailing list [email protected]
