Philip Brown writes: > James Carlson wrote: > > I hear you, and I understand why you're complaining, but I simply > > disagree. For the case you're citing, a contract was a better way > > out, as was filing a bug and making sure that the powers-that-be know > > that having no stable interface is a serious problem with the system. > > What do you mean by "a contract"?
http://www.opensolaris.org/os/community/arc/handbook/contract/ > Sounds like "a commitment to support an > interface, in the way it is now, on an ongoing basis". Not exactly. It's an agreement between a supplier and a consumer to allow the use of an interface in some way other than how it was intended to be used. It doesn't necessarily mean "support." The terms of the contract are up for negotiation. The terms could specify support, or mere notification, or a versioning scheme, or something else. > That is explicitly NOT what I am asking for. I am NOT suggesting that all > interfaces be stable and committed to. Then you're explicitly asking for arbitrary breakage without notice. That's really the only alternative. If something isn't stable enough to build on (by exported stability level), and you're not asking for it to be made stable enough for *you* to use (by use of a contract), then you're accepting that it'll change arbitrarily and without notice at any time, and that your software will fail. The result is broken software in customer hands. As a fundamental rule, nobody at Sun wants to ship software that breaks easily and without notice. I'd go so far as to suggest that (if it isn't yet), then not shipping broken things ought to be a core OpenSolaris value as well. > Aas far as "filing bugs" go... I dont have much confidence that filing a bug > "there isnt enough documentation on this", is going to go anywhere. Do you? I do. I've seen dozens of them. > be honest now. if they are "too busy" to write it up in the first place, I > dont think that some random person filing a bug, is going to get much > traction either. Often the issue is simply that the supplier doesn't *know* of anyone who might want to use it. Sometimes the supplier does know, but doesn't have the proof necessary to fund a project to do the right thing. In all those cases, having concrete complaints from actual users *helps*. Bugs are one means of communicating with a project team. (Not the only one, but sometimes an effective one.) > Once again, please note that I was not complaining about lack of a "stable" > interface. In that case, use whatever you want. Just don't come crying foul to the ARC when your software falls apart in the user's hands. > > That explicitly disallows a set of cooperating projects to share > > interfaces that they need without nailing those interfaces to a tree. > > well, gee.. if there are "cooperating projects, sharing interfaces"... it > seems like the sane thing to do, would be to DOCUMENT those interfaces, to a > level suitable for (semi)-project-external use, wouldnt it? :-) That just > seems like good technical practice to me. Not necessarily. Hence the point of contracts. > However, by dint of your hypothetical situation about two projects sharing > an interface... I think that also in and of itself, should never be allowed > to be private, in the context of OpenSolaris. > In my opinion, it should be on the public source tree, and documented as an > interface. Otherwise, you just removed the "open" from "opensolaris". Private, as has been stated many, many times now, does not mean "secret." Please don't misconstrue it that way. It has nothing whatsoever to do with "openness" for OpenSolaris. It has everything to do with modular software design. You can see all private details in the source code itself, in the design and other documentation published by project teams (and required of them for C-team review), and often in the ARC project logs as well. These things aren't intended to be secrets. Please don't spread that kind of FUD. > [if a developer is already share-minded enough to be sharing with "another > project".. the incremental effort to share more widely, should be relatively > small] That's flatly incorrect. The incremental cost of dealing with more consumers on an unstable interface is often very high. It's sometimes possible to notify a handlful of people and coordinate an incompatible change. It's almost never possible to do that with dozens or hundreds (some will refuse or will have died). It's simply impossible with an unknown number of others. Private interfaces that have a small number of contracted consumers are possible. The ARC will generally _strongly_ advise that an interface be made public if there are a large number of contract holders, as it's clear that the chance of making a change work approaches nil with large numbers of contracts. > > By saying "no private interfaces," you're going too far in the > > "everything must be stable" direction. > > no, I'm not. > > What I'm doing, is insisting on minimally documented interfaces. not stable > interfaces :-) Please don't confuse official system documentation (man pages), which is required for public interfaces, with the artifacts of ordinary software development work, such as design documents. You're asking about the latter. The public/private distinction is mostly about the former. > > The result is either that the > > owners of those interfaces are unable to change anything (for fear of > > breakage), or they're constrained in the changes they may make > > (certain redesigns are off the table, even if they're "right"), > > This sounds like a political problem, in that sun managers are not > supporting the definitions, or the people who work under them. It's a > political problem that the managers are not saying "do the right thing", but > "play politics". You're misreading it. The constraints you've quoted from me above are *BECAUSE OF KNOWN CONSUMERS!* Nobody wants to break software. Period. It's really that simple. If there are consumers of your interfaces, then you can't make incompatible changes in your interfaces without making sure that those consumers change as well. One way to deal with that is to have a contract -- so you know who the consumers are and what they require. Another is to simply declare that you'll never make such changes ever. It's unacceptable to make incompatible changes and just hope for the best, or pretend as if broken software doesn't matter. That's not engineering. > Or on the other side, managers of people who used an unstable interface, are > improperly putting pressure on other people, instead of making their OWN > team rewrite the code once the interface has actually changed. Once again... > a political problem. Managers doing the "cheap/easy thing", instead of The > Right Thing. > > So... fix your managers. Dont hobble better technical practice, because of > poor internal management practice. Sorry. We're not talking about a political issue here. We're talking about Mother Nature. She won't allow you to change an underlying piece of software in an incompatible way without unmodified things that depend on it also failing. Even without an ARC or managers or budgets, Mother Nature will hunt you down. ;-} Richard L. Hamilton writes: > Every file format and non-static function call or external variable > is _potentially_ an interface. If they were all documented to the level > that someone not working closely on that particular bit of code could > safely manipulate them, I suspect little other work would get done. Quite true. > That having been said, I'd like to see most of whatever documentation > already exists for contracted or consolidation-private (i.e. multi-project) > private interfaces made available, with some boilerplate disclaimers added > if that will make happier those worried that someone might misconstrue that > documentation as some indication of stability that it isn't. Quite a lot of it is in comments in header files. More is in design documents on opensolaris.org. Yet more is in ARC cases. > If the code is open, then whatever documentation already exists (not > necessarily > implying that more must be written) should ideally be released too. Strongly agreed. Those are design documents, though, not committed interfaces. There's a big difference in a well-designed system. > IMO the earlier point also holds that if there's no other way to do something > than via a private interface, then there should be an RFE for a public > interface > to do the job. Also strongly agreed. > But I suspect getting a "contract" on some private interface needn't be > incredibly > difficult, and if there's very few potential consumers, may be cheaper or more > flexible than promoting it to a public interface, and would certainly be more > maintainable than just using it (documented or not) without some assurance > of notification of future changes. It's worth the discussion, at least. Simply driving on and pretending there's no problem is foolhardy at best. -- 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
