On 04/ 9/10 05:51 AM, James Carlson 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.
I honestly can't see what value a list would add to this case.
The examples in the case material provide way more information
than such a list because they provide context, and one can
always obtain a list by running kstat at the command line.
If an interface table is desirable, how about:
Interfaces
________________________________________________________________
| Imported Interface | Classification | Comments |
|________________________|___________________|__________________|
| smbsrv kstats | Project | |
| | Private | |
|________________________|___________________|__________________|
Alan
_______________________________________________
opensolaris-arc mailing list
[email protected]
