[arc-discuss] When should interfaces be private?

[James Carlson]

Darren Reed writes:
> James Carlson wrote:
> > ...
> > Note that this is the important point here: project teams are on the
> > hook to provide architecturally significant details for their
> > projects.  The ARC isn't supposed to go ferreting this information
> > out, and the project team isn't supposed to hide behind a "everything
> > we're doing is private" smoke screen.
> >   
> 
> That's quiet right.
> 
> Maybe what I'm looking for, some rule about what should be classified X vs Y
> depending on Z, just doesn't exist outside of the project saying X is 
> ready to be Y.

If I understand the question, I don't think there is such a written
rule other than the broad outlines in the introductory documents:

  http://www.opensolaris.org/os/community/arc/arc-faq/arc-review-overview/

We rather intentionally have not stated mechanical rules about what
gets reviewed *because* we expect those participating in the process
to use a fair amount of judgement in their interactions with the ARC.
We expect those unfamiliar with the process to seek out interns and
members who can help them complete ARC review successfully.  For
longer-term handling of the issue, we expect to recruit ARC
participants in diverse communities, who then serve as local process
gurus, in addition to helping review projects.

The things that must be reviewed are those that are architecturally
significant.  It's really as simple as that.  If the things that are
significant are all labeled "Private," then that's what's under
review.  If the private bits are trivial architecturally (merely an
internal code management issue, perhaps), then they needn't be
included (but may be anyway if desired).

It's even true that higher-stability interfaces are frequently
unreviewed.  For example, nobody cares if I'm using printf(3C).  It's
a Committed interface, and I'm importing it, but it's extremely
unlikely to change, so my use of it is not architecturally
significant.

Thus, there's no solid relationship between stability level and the
need for review.  Attempting to map one into the other is (in my
opinion) just a mistake.  (There may be some simple rules that work
that way -- "new Committed interface always needs review" -- but the
problems and misunderstandings are never in the simple cases.)

And it's true that interfaces are not the only thing the ARC is
looking at.  The ARC looks at software architecture, which can include
high-level software component relationships (aside from and in
addition to the interfaces between them), security and performance
considerations, and requirements or restrictions imposed on or by
other projects.

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