[Note that this initial proposal changed significantly during the course of the email discussion; the v3.1 interface taxonomy reflects the final modified proposal - Editor] Introduction: ============= This document is a thumbnail to facilitate a discussion of a change to the Public side of the Sun Interface Taxonomy. Although the changes are fairly substantial, they are evolutionary in nature. This document is not the final specification to be approved - that will be a rewrite of the Sun Taxonomy Document itself. Currently Public / Private is just a line which subdivides the classifications into two sets. The rough line is "those that are documented to the public, and those that are not". Note that the two sides of this line work on entirely different concepts: Public: When an interface can change Private: Who can consume an interface. Many moons ago, the Public taxonomy was as simple as the statement above. This simple concept was first confused by the addition of Evolving, but the confusion became painful with the addition of External. This proposal is an attempt to refocus the taxonomy on the original core concept. The need for such a refocusing has been shown by the misinterpretation of Evolving and External by many Sun projects. With the increased exposure of our taxonomy to external organizations (due to FOSS), we also should be proactive about not confusing this broader audience. Assumptions and Ground Rules: ============================= The Private side of the line seems to be working just fine, so I'm not inclined to mess with it. Please do not propose changes to the Private taxonomy levels as part of this discussion. That can be your headache if you feel changes need to be made. We love to get lost in discussing what the appropriate names for the various levels are. Certainly some of our names are not common usage and perhaps even pejorative. In this discussion we can debate the new proposed names (Volatile and Undefined) and *perhaps* consider renaming the little used Unstable (but I propose not to). However, the remaining terms are too well established in both our collective consciousness and documentation. Please refrain from suggesting renames of these terms. There is one definition we (Sun) use for each of these levels. Local customizations are not allowed. There is no justification for parts of Sun using different definitions; that only serves to confuse our customers, who are the ultimate consumers of these definitions. In contrast to the above, different parts of Sun may more heavily utilize some levels more than others. For example, in the web services area, most administrative CLIs are Unstable while in the legacy OS/Net area they are almost universally Stable (or Evolving). This ostensibly reflects the market expectations in these areas. (ARC reviews should validate such claims about market expectations as real and that teams aren't just being lazy or shy). We need to remember that these apply to individual interfaces, not products or consolidations. I've often said "Mozilla is External"; that is technically a syntax error. It may seem a harmless syntax error if Mozilla is composed of 99.44% External interfaces, but it is not. If the *right* .56% of the Mozilla interfaces were "External Stable", Mozilla might be better viewed as Stable and it certainly would be appropriate as a core component of the system. (Yes, I have my list of what those .56% of the interfaces are.) With respect to external communities, we need to (choose one): 1) establish a "lingua franca" with the community. 2) establish a mapping from their terminology to ours. If we can't do either of the above (ie: They don't care about stability) we should probably never apply more than the "External Volatile" level and never use the external component as a core component. (Note: Volatile can be useful for some things but is pretty valueless for programmatic APIs.) This problem can only be mitigated by a willingness to commit resources to address incompatibilities and a willingness to fork from the community if necessary (at least until a Minor release point). We want to get to a point with certain important, trusted communities to actually believe their classifications. What is beautiful world it would be if GNOME could assert "Stable" and we could believe them! The interface taxonomy does not address the periodicity of releases or the types of releases done by a product. In Solaris, J2SE and other products which focus on supporting existing customers which are resistant to synchronization points, Major releases are not expected to ever occur. In Solaris, even Minor releases are fairly infrequent occuring once every 2 to 4 years. Other products which are either new to the market or have a customer base which values inovation over stability may do Major releases on a fairly regular basis. The actual calendar time a commitment represents depends upon the product it is integrated into. PSARC has already verbally committed to the elimination of the Evolving classification. The rationale is that Evolving has always had a conflict in its definition: Customers are encouraged to use this interfaces. Often the Evolving interface is the only way provided to perform significant functions. They may change at unspecified times. The first two items lead even our best intentioned customers to use these interfaces. Should they change, the significant customer would just escalate. The bottom line is that Evolving is simply false security to our developers and indistinguishable in reality from Stable. I was surprised to discover that not all members of the ARCs other than PSARC agree with this view, hence it is certainly open for discussion. However, I hope to obtain a fairly quick consensus on this point (one way or the other) and I hope all will be open to that consensus. Finally, PSARC also verbally approved the addition of something conceptually equivalent to what is proposed as Undefined in this document, but called Volatile at the time. Don't be confused by this reassignment of monikers. Proposed Interface Taxonomy: ============================ We have three (or four) cases of when things can change (the fourth just adds a convenience term): Stable: Incompatible change only in Major Releases[1][2] Unstable: Incompatible change only in Minor Releases Volatile: Incompatible change at any time, incl. Patch Undefined: Not an interface. The intended usage is to flag items such as "human readable output" and graphical layout as clearly not intended to be interfaces. Note that for all of these, this is the default assumption about when SAC should approve incompatible changes. It is never a license to make an incompatible change (or *any* change) without review. As always, the interface level assigned must be appropriate for the intended use of the interface - they should not reflect the source of the specification (see below) or the project staffing level. However, it should be understood, that only a small number of Stable interface in a sea of Volatile with a component can still yeild an appropriate core component. The important interfaces should be Stable. Then come the possible adjectives. The first is "who controls the public spec?": Internal: (Silent default) Public specification controlled by Sun Microsystems. Standard: Defined by a versioned standard by an external body which tends to behave as one would expect (yes, the exact definition of a standards body is loose and the gray zone has occasionally been a problem, but let's not add this detail to our plate). To this point, we've only used this as "Standard Stable", but the others make sense. It's not likely we would tweak these in a Minor release, but we could remove one entirely (the ultimate incompatible change). External: Controlled by a "less than standards body" external organization, usually referred to as a "community". May or may not have clear specifications (much less versioned specifications). However, specifications clear enough to identify incompatible change must be presented to the SAC process (yea, it must be defined). The code itself ideally would never form the specification and for Stable and Unstable it should be absolutely refused. One should note that these adjectives only convey a minor refinement to the underlying base term. As always, in the case of Standard it only implies minor additional stability because we couldn't change the specification, even if we wanted to. In the case of External, it only implies minor additional instability, because since we don't control the specification, and additional "exceptional case" (see [1] below) comes into play. In all cases, every possible effort should be made to respect the contract with the interfaces consumers expressed by the underlying base term. The second possible adjective is Obsolete, with the same meaning as the existing base term. It is changed from a base term to an adjective in this proposal so that the change limitations conveyed by the base term are not lost when it is applied. Obsolete: (Defined as before). The third possible adjective is one we are already familiar with, although previously it has only been applied to Private interfaces: Contracted: (Defined as before). It has been noted that the current definition of Unstable has a restriction that, although Public, other Sun products/components may not depend upon them. (After all, it probably isn't wise for an ISV to depend upon these, why should we in the same role?) Although rare, with the expected increased use of Unstable (and perhaps Volatile) it is expected that some Sun products/components will want to register dependencies on these. (If they don't release simultaneously, its probably not a good idea.) This adjective (just as in the Private use case) serves to acknowledge the existence of such dependencies. Old to New Mapping: =================== The following table provides the mapping of the old taxonomy levels to the new ones: Old New ---------------------------------------------- Standard Standard Stable Stable Stable Evolving Stable Unstable Unstable External External Volatile Obsolete Obsolete Stable These mappings will be made public (as in published) to avoid having to perform a massive scan of the man pages to alter the terms. Specifically: Interfaces formerly declared Evolving are now Stable. The simple term "Standard" is shorthand for "Standard Stable". The simple term "External" is shorthand for "External Volatile". The simple term "Obsolete" is shorthand for "Obsolete Stable". Footnotes: ========== [1] Although Sun has always had a very rigorous definition of Stable, a few exceptional case allow incompatible change (or removal) of Stable interfaces. Some of these have always been part of our standard operating procedure and have been stated in various cases. To the best of my knowledge, these have never been gathered in a single place. We do so now. These are: 1) *Must* change the interface to close a security hole or data corruption bug. The vundrability is inherent in the interface and not just a vestige of the implementation. 2) Expected Change - to not make the change would be unacceptable to the **vast** majority of our customers, because the expectations have changed. An example of this is the incompatible changes made to pcfs in response to Windows moving away from 8.3, case insensitive naming to unrestricted, case sensitive naming. Our customers would expect this change, incompatible or not. Note that the customer expectation must be very obvious to meet this criteria. 3) The world has moved on and there is believed to be very near zero usage of the interface. This is rarely (ever?) a reason to modify an interface, but occasionally it is a reason to remove one. 4) For External interfaces, the community and customer expectation has changed. By not tracking the community, we are performing a disservice to our customers. Note that in all cases (except perhaps #3), these exceptions only tend to be granted when there is no practical way to engineer around the incompatibility. [2] Note that most products/components should contain at least one Stable interface. If the entire product is composed of nothing other than Unstable (or less stable) interfaces, the Major number on the product becomes useless and we are engaged in nothing other than stability deflation at the expense of our customers. (The suggested exceptional case is a product composed entirely of Unstable interfaces, where each has an small probability of change - This needs more thought.)