Interface Taxonomy

Interface Taxonomy

Copyright 1991-2006, Sun Microsystems, Inc

Policy Synopsis

The Interface Taxonomy is a classification scheme for interfaces which is used to ascribe a stability classification to an interface.
Interface taxonomy classifications are provided to give guidance to users as to the appropriateness of an interface for a given task in a specific usage environment. Project teams typically propose to the ARC a stability classification for each of their new or changed interfaces. ARC opinions identify the stability classification accepted by the committee for each interface.
The stability classification identifies:

• who may use the interface -- that is, the architectural level at which the interface is exposed;
• the risk of possible breakage or incompatibility; and
• the commensurate constraints on incompatible change to the interface.

Contents

• Interface Taxonomy
• Audience
• Background
• History
• Policy
• Advice
• Glossary
• Implementation
• Conformance
• Exemptions
• Appeals
• CaseHistory
• ManPages
• References
• PolicyChangeLog

Overview

Audience

This document was written for software developers who are managing stability expectations for the components and features they are developing.

Consumers of these components and expectatons (peer developers, project and program management, ARC members and ISVs) also need to understand the concepts in this classification scheme.

This taxonomy is used extensively by the ARCs to ensure that newly created interfaces have explicit stability expectations and that those expectations are met over time as a component evolves.

Background

 Interface taxonomy  stability classifications are provided to give guidance to users as to the appropriateness of an interface for a given task in a specific usage environment. Project teams typically propose to the ARC a stability classification for each of their new or changed interfaces. ARC opinions identify the stability classification accepted by the committee for each interface.

 Stability classifications defined in this document should be spelled uniformly with initial capitals, to differentiate them from the common English words (e.g., Committed, Uncommitted, Project Private).

 The interface taxonomy stability classifications in this document may be divided into two broad, distinct groups:

• Public: (Committed, Uncommitted, Volatile, Not-an-interface)
   With a few restrictions within Sun (see individual descriptions) Public interfaces may be used by anyone. The levels are differentiated by when the interface may change incompatibly, in terms of release vehicle type. Public interfaces are expected to be externally documented, usually in the form of manual pages, with the taxonomy classification specified.
• Private: (Sun Private, Committed Private, Consolidation Private, Project Private)
   The levels are differentiated as to who may use the interface. There is no formal restriction as to when the interface may change, but because change is expected to be coordinated between the providers and consumers of the interfaces practical considerations exist. Private interfaces are usually not externally documented, but cases exist where customers are best served by minimal documentation. In such cases any provided documentation should make it clear that the interfaces described are Private and not for public use.

History

 Previous versions of this document focused Public commitment levels exclusively on a guarantee as to when an interface would not change incompatibly. Over time, additional commitment levels were introduced to convey intent (rather than guarantee) or restrict the source of the change. These well intentioned additions were found to be counter-productive due to multiple interpretations and misinterpretations. This revision simplifies the taxonomy, reverting back to a state closer to its original form. Appendix A presents the classification levels deprecated by this revision and provides mapping details from those deprecated levels to the current levels.

 This version also removes the association of "compatible changes" with stability/release taxonomy levels. That is, Committed/Stable interfaces could not change in a compatible way in other than a Minor release. This was intended to provide a mechanism for managing dependencies on new features (i.e., the new feature Foo(Committed) could be used in versions newer than r3.5). This capability was never effectively communicated to customers and was commonly ignored by developers, so it was dropped from this version of the taxonomy.

 The following table summarizes the mapping of "Interface Taxonomy revision 1" levels to "revision 2" levels. The details are provided in the individual rationale that follows. Note in particular the caveats and special conditions related to the deprecated Evolving classification. 

• 
  
  • Standard
     The Standard classification was historically hindered by the question of what exactly an "standards organization" is. The outside organization which controls the interface may be ISO or ANSI at one end of the spectrum and Zelda of "Zelda's Software and Tea Cozies" at the other. Where to draw the line between these two extremes often made application of Standard difficult.
     As with External, binding the classification to the organization which controlled the interface specification detracted from the central point of when the interface might change incompatibly. From this perspective, Standard was always equivalent to Committed.
     All interfaces previously classified as Standard may now be considered Committed, with the additional expectation that a reference to the organization which controls the interface specification be recorded.
  • Evolving
     Evolving has always had two contradictory attributes: it has the ability to change in a Minor release, yet third parties are encouraged to make use of the interface. This contradiction has caused significant difficulties outside of the ARC process (e.g., appcert).
     Within the ARC process, the different ARCs have been applying different interpretations of Evolving which had lead to confusion and conflicting expectations.
     PSARC (and perhaps other ARCs) focused on the text of the definition, which paints Evolving as only slightly less stable than Committed/Stable. It takes an exceptionally problematic situation to motivate incompatible change to an Evolving interface. Over the 7 years this classification level has been in existence, no Evolving interface approved by PSARC has been incompatibly changed. More importantly, the exact same discussion and conclusions would have occurred if the interface in question was Committed/Stable or Evolving. In general, Evolving was nothing more than a "Don't Panic" salve for developers of new interfaces.
     History shows that the promotion of Evolving interfaces as described in that "NOTE" in the previous definition has only rarely occurred. This has lead to a situations where many interfaces have become "effectively Committed" because many ISVs have utilized them, yet are labeled with an inappropriate "thin ice" warning.
     LSARC (and perhaps other ARCs) focused on the "Incompatible Change" attribute of Evolving, making an Evolving interface effectively an Uncommitted/Unstable interface without the somewhat pejorative implications of the (previous) Unstable label.
     All Evolving interfaces approved by PSARC may be considered Committed with the adoption of this document version. All ON-delivered documentation will be modified to reflect this change. All other Evolving interfaces should be considered Uncommitted, which is the default transition path.
  • External
     What's in a name? It seems that in the case of External, the answer is "everything". The name External was chosen for this level, because it could only be envisioned as appropriate where the interface specification was controlled by an external body. Unfortunately, it has often been interpreted as the required classification level for all interfaces where the specification was controlled by an outside body. This was never the intent as is captured in PSARC/2001/313 which originally created the External classification level.
     The change of External to Volatile is little more than a name change, accompanied by allowing interfaces controlled by the implementation provider to be labeled as Volatile. That said, it is expected that the application of Volatile to an interface controlled by the implementation provider will be an exceptionally rare event and that the classification will be temporary.
  • Obsolete
     Obsolete was moved from "classification" status to "modifier" status to help regularize the taxonomy. In concept and application it is unchanged.

Policy

• Applies to All software produced by SMI
• Authority SAC
• Approval SAC
• Effective April, 1992
• Policy 
  • All software interfaces must be classified according to this taxonomy. Interfaces are defined as APIs, files and directory structures, file formats, protocols, (sometimes) even performance and reliability behaviors, and any other attribute upon which another component might reasonably depend.
  • An ARC must review, approve and archive the specification for all interfaces other than Project Private and Internal. Unreviewed, unapproved interfaces are assumed to be Internal. An adequate specification, suitable for archiving must exist for all interfaces submitted for review. Often Project Private interfaces are also reviewed if the presentation of them aids the understanding of the entire project or it is expected they will be promoted to a broader classification in the future.
  • Adequate customer documentation must exist for all Public interfaces. It is strongly preferred that manual pages exist for all Public interfaces (supported on Solaris), even if only significant content of those pages are SYNOPSIS and ATTRIBUTES sections and a textual pointer to other documentation. Independent of the form of documentation delivery, the interface taxonomy commitment level must be presented to the consumer.
  • In cases where the organization delivering the interface implementation does not control the interface specification, the controlling body must be be clearly cited in the documentation. In the case where a well-defined, versioned document is the specification, both the name and precise version must be be cited.
• Details  === Public Interface Classifications|Committed (formerly Stable, Public; encompasses Standard, Evolving)

• 1. Interfaces that are experimental or transitional. They are typically used to give outside developers early access to new or rapidly changing technology, or to provide an interim solution to a problem where a more general solution is anticipated.
  2. Interfaces whose specification is controlled by an outside body and the implementation provider is only willing to commit to forking until the next minor release point should that outside body introduce incompatible change. Note that this "middle of the road" approach is often the best business decision when the controlling body hasn't established a history of respecting compatibility.
  3. Interfaces whose target audience values innovation (and possibly ease of use) over stability. This attribute is often asserted for administrative interfaces for higher web tier components. Note that ARC review may request data to support such an assertion.
      A project's intention to import an Uncommitted interface from another consolidation should be discussed with the ARC early. The stability classification of the interface -- or a replacement interface -- might be raised. The opinion allowing any project to import an Uncommitted interface must explain why it is acceptable, and a contract must be put into place allowing this use. For Sun products, the similarity in the usage of Uncommitted and Consolidation Private interfaces should be noted.
      Any documentation for an Uncommitted interface must contain warnings that "these interfaces are subject to change without warning and should not be used in unbundled products". In some situations, it may be appropriate to document Uncommitted interfaces in white papers rather than in standard product documentation. When changes are introduced, the changes should be mentioned in the release notes for the affected release.
      NOTE: If we choose to offer a draft standard implementation but state our intention to track the standard (or the portions we find technically sound or likely to be standardized), we set customer expectations for incompatible changes by classifying the interface Uncommitted. The interface must be reclassified Committed when standard is final. Such an intention could be encoded "Uncommitted->Committed".)

• 
  
  • Security, Authentication
  • The existence of (perhaps vestigial) Manual Pages and conformance to Sun section numbering
  • File System Semantics (Solaris examples: /usr may be read-only, /var is where all significant run-time growth occurs, ...)
     All Volatile interfaces should be labeled as such in all associated documentation and the consequence of using such interfaces must be explained either as part of that documentation or by reference.
     Shipping incompatible change in a patch should be strongly avoided. It is not strictly prohibited for the following two reasons:
  • Since the patch provider may not be in explicit control of the changes to the upstream implementation, it cannot guarantee with reasonable assurance that an unidentified incompatibility is not present.
  • A strong business case may exist for shipping a newer version as a patch if that newer version closes significant escalations.
     In general, the intent of allowing change in a patch is to allow for change in Update Releases.
     Sun products should consider Volatile interfaces as equivalent to Consolidation Private. A contract is required for use of these interfaces outside of the supplying consolidation.
     Extreme care in the use of Volatile interfaces is required by layered or unbundled products. Layered products that depend upon Volatile interfaces must include as part of their review material how they intend to manage the dependency. It is not explicitly prohibited, but it is probable that unbundled or layered products that ship asynchronously from the Volatile interfaces upon which they depend will face nearly insurmountable difficulty in constructing a plan to manage such a dependency.

Private Interface Classifications

Modifiers

 Modifiers may prefix a compatibility level to modify its meaning. ===

Contracted
:
 The modifier "Contracted" may be applied to any interface classification level (although it makes little sense to apply it to Committed). It serves to indicate that one of more consummers have been granted additional privileges with respect to the use of the interface.
 Care must be taken not to overuse Contracted interfaces. By their very nature, they require more detailed and interface-specific attention than their non-contracted equivalents, so that they impose additional hidden costs on the engineering community. Although a Contracted interface may superficially appear to be a cheap answer to a design problem, it is likely that a non-contracted but more stable interface will cause fewer problems in the long run.
 The most common usage is to apply Contracted to a Project Private or Consolidation Private interface to allow a controlled set of consumers outside of the normal domain of the normal interface classification level to consume the interface subject to a set of restrictions or conditions expressed in a contract.

  Example: If a Propect Private interface needs to be used by another entity within a consolidation, but it is not appropriate for it to be used by everyone else in that consolidation, it would use Contracted Project Private with a specified list of contractees instead of the more general Consolidation Private.

 The other common usage is to allow a Sun product to use an Uncommitted or Volatile interface supplied by another consolidation.
 A  boilerplate contract form exists (targeted at interface being Consolidation Private).
 The minimal requirements of a contract are that it identifies the functional supplier and proposed consumers of the interface in terms of product (not management) structure and states the process to coordinate change in the event of an incompatible change to the interface. In rare cases, the process may be as minimal as notification.
 Contracts are reviewed, approved and archived by the ARCs just as projects are.
 An interface becomes "Contracted" with the approval of the first contract. It is worth noting the intent to allow contracts to be written against an interface as part of the initial submission, but the Contracted modifier is only officially applied with approval of the first contract.

Obsolete
:
 The Obsolete modifier indicates an interface that is "deprecated" and/or no longer advised for general use. An existing interface may be downgraded from some other status (such as Committed or Uncommitted) by the application of the Obsolete modifier to encourage customers to migrate from that interface before it may be removed (or incompatibly changed).
 If the interface is to be removed (or incompatibly changed) in a release where its former stability level would not have allowed such a change, a proactive program to communicate to customers the change in commitment must precede the change.

 [*] For some interfaces, the ARC may find such a communication program appropriate before removing an interface, even if the release level nominally allows such a change.
________

 The standard program to communicate a change in commitment requires:

• 1. Demonstration of support by the PAC responsible for the deliverable(s) containing the interface. Such support can be demonstrated by a change to strategy document or resolutions taken in meetings and documented in the minutes.
  2. One year's notice to the customer base and the product development community of the intended obsolescence of the interface. This requirement ensures that no further commitments against the interface are created and gives those affected by future removal of the facility a chance to make alternative arrangements.
      The year must elapse after the notice and prior to the delivery of a product that contains a change incompatible with the present status of the interface.
      Acceptable means of customer notice includes letters to customers on support contracts, release notes or product documentation, or announcements to customer forums appropriate for the interface in question.
      Mail to all-smi-engineering@sun.com is considered to be the standard means of providing notice to the Sun internal product development community. Other communities using this taxonomy are expected to have their own notification distribution mechanisms.
      The notice of obsolescence is considered to be "public" information in that it is expected to be available freely to the customers. It is not intended that this require specific actions to "publish" the information, such as press releases or similar forms of publicity.
  3. Where technically feasible, inclusion in the release where the interface is declared Obsolete of a warning mechanism if the interface is used. The mechanism should produce a message of the form

  The application uses interface which has been declared obsolete and may not be present in versions of <product> of released after <date>. Please notify your support person. See XXX for more information.

 One suggested method is to use syslog(3), with a level of "LOG_WARNING". A method for turning off the warning message should also be provided. Common sense should apply in determining how often the warning should appear.

• 
  
  1. Information in the User Documentation that contains the following:
     *1* An explanation of the meaning of Obsolete.
     *1* An indication of the kinds of warning messages that may appear.
     *1* A suggesting that the customer ask their support person to contact the vendor of any application that causes such a warning to appear.
     *1* General instructions for turning off the warning messages.
     *1* A list of the Obsolete interfaces contained in this release, the earliest that they may disappear, the kind of warning that might appear, and the method for disabling the warning.
      Proposals to downgrade an interface through this mechanism must be approved by an ARC before "core" documentation may be altered to identify the interface as Obsolete. Release notes may warn of the possibility of removal with either ARC or PAC/P-Team approval. (A warning that the interface *may* be removed in a future release could be included without ARC approval, but the ARC may not deem such notice alone as sufficient notification to customers to "start the 1-year clock".)
      A follow-on project to perform the actual feature removal in a forthcoming minor or major release (after the timeout period expires) requires architectural approval to ensure that the requirements of the obsolescence policy have been met. Provided they have been met, approval will be straightforward.

Advice

Interface Stability Considerations
 When a project team proposes (or an ARC reviews) an interface's stability classification, consider and discuss with the ARC: 

• 
  
  • Who are the desired consumers of the interface? What stability levels will those consumers require?
  • What evolution do you envision or even imagine? Does the design of the interface allow sufficient freedom to evolve the interface compatibly?
  • Assure that you understand the constraints on future evolution entailed by the stability level. Does the stability classification allow sufficient freedom to evolve the interface if an incompatible change is required?
  • Assure that product/project documentation sets consumer expectations appropriately.
  • This document describes generally-understood stability levels; try to avoid making up new ones, as lengthy discussions about precise semantics are likely to ensue. Sometimes subdividing an interface into portions of differing stability classifications is advisable.
  • Maintain and evolve the interface only in manners consistent with its stability classification.
    Special Considerations for Libraries
     Shared libraries must be and built with a version number, so that incompatible changes (either dropping a symbol or altering its semantics) can be reflected by incrementing the version number.
     A single library exposing API symbols to customers normally does not mix Committed interfaces (which are unlikely to be changed incompatibly) and Uncommitted/Volatile interfaces, which are more likely to change incompatibly. If they were mixed, when changes to the less-stable interface require bumping the version number of the library, that could cause disruption for users of the more stable portions. Private symbols will likely also exist in all libraries.
     The Solaris 2.5 Linker and Libraries Guide's "Versioning" chapter explains how version names can identify the stability classification of the interfaces and inter-release compatibility. The same chapter also explains how "scoping" can hide symbols. Project Private symbols can become Internal symbols, avoiding any possibility of their use outside the library itself. Suggested usage of these facilities is available in "/shared/ON/general_docs/scoping_rules.ps", as well as in the Libraries Best Practice
    Deprecated stability levels

Standard => Committed
:
 The former definition of Standard was:

 |Standard

Evolving => Committed
:
 The former definition of Evolving was:

 |Evolving (formerly "Uncommitted", but so was what is now "Unstable")

• 
  
  • clearly setting customer expectations about the circumstances under which the interfaces might change.
  • ensuring that all such changes are described in the release notes for the affected release.
  • providing migration aids for binary compatibility and/or continued source development.
     A project's intention to accept the risk of depending on an Evolving interface must be evaluated and explicitly approved by an ARC.
     NOTE: It will often be the case that interfaces declared to be Evolving will later be reclassified as Stable or Standard. (This might mean that the examples above are no longer Evolving.) Nonetheless, foreseen promotion is not a necessary attribute of the Evolving taxonomy level. An interface could be classified Evolving and remain as such indefinitely.

External => Volatile
:
 The former definition of External was:

 |External

• 
  
  • Security, Authentication
  • Manual Page Section Numbering
  • File System Semantics (/usr may be read-only, /var is where all significant run-time growth occurs, ...)
     All External interfaces should be labeled as such in all associated documentation and the consequence of using such interfaces should be explained either as part of that documentation or by reference. Default search paths should not lead to External interfaces - the user should be required to take some simple, explicit action to access them.
     Shipping incompatible change in a patch should be strongly avoided. It is not strictly prohibited for the following two reasons:
  • Since Sun is not in explicit control of the changes, it can not guarantee with reasonable assurance that an unidentified incompatibility isn't present.
  • A strong business case may exist for shipping a newer version as a patch if that newer version closes significant escalations.
     In general, the intent of allowing change in a patch is to allow for change in Update Releases.
     Extreme care in the use of External interfaces is required by layered or unbundled Sun products. Layered products that depend upon External interfaces need to include as part of their review material how they intend to manage the dependency. It is not explicitly excluded, but it is probable that unbundled or layered products that ship asynchronously from the External interfaces upon which they depend will face nearly insurmountable difficulty in constructing a plan to manage such a dependency.
     It should be noted that in some cases it will be preferable to apply a less fluid interface classification to an interface even if the controlling body is external to Sun. Use of the Unstable classification extends the stability commitment over micro/patch releases, allowing use of additional support models for software that depends upon these interfaces, at the potential cost of less frequent updates. However, care should be exercised because it will be difficult to differentiate External and Unstable as a classification for seemingly identical freeware. It is suggested to use External and behave (through contracts) as Unstable. Use of the Evolving classification promotes these interfaces to first class Sun interfaces, at the potential cost of diverging from the external specification. By using Evolving, Sun is essentially taking control of the interface, although it may liberally import from the external reference. Use of the Stable classification is not recommended.
    Contracted External
     This stability level is the same as External, except that a contract has been put in place between the provider and consumer of the interface. The contract describes special arrangements made for the stability of the interface. This can be used, for example, to place restrictions on how and when an interface may change if the normal rules for External do not satisfy the requirements of the consumer.
     An ARC should review, approve, and archive a contract between the provider and consumer of the interface. Any change to the contract, the interface, or the specification requires reapproval.

Obsolete => Becomes a modifier for other levels, not a level of its own
:
 The current decription of the Obsolete modifier is the same as the former description of the Obsolete stability level, and is not repeated below. The previous definition of Obsolete was:

 |Obsolete

Glossary

Interface
 SAC uses the term "interface" broadly, to mean any part of any specification that defines the interactions among hardware or software components, between invocations of the components, or between humans and these components. An interface normally includes both syntax and semantics.
 This includes Graphical User Interfaces (GUIs); commands, daemons, and their options; functional interfaces such as an Application Programming Interface (API); data structure or class declarations shared between components; protocol specifications; file formats (inputs accepted, configuration files, and output file formats); mandated file names; defaults; and package abbreviations. See your ARC's questionnaire.
 An implementation of an interface also has behavioral artifacts, such as performance under certain conditions, which are not specified, and are therefore not part of the "interface". The developers of the implementation do not assume anyone is depending on these undocumented features; a client should not depend on these artifacts (or should get their dependencies made an explicit part of the specification). However, the capacity of an interface or its gross performance characteristics could be deemed an implicit part of its interface semantics.
Specification
 An interface specification documents the purpose, syntax, semantics, and limitations of the interface. The specification's purpose includes understanding the interface, implementing or maintaining it, determining compatibility (say, between releases). The specification may be the same document used by clients, consumers, or importers of the interface, or a separate document with that specific point-of-view might be more suitable.
Open specification:
 An interface specification is Open if it is published, customers are free to use it (i.e., build internal or commercial products that use our implementation of the interface), and others are free to provide alternative implementations, without licensing or legal restrictions. Interfaces with Open specifications may be called "Open Interfaces".
Closed specification
 An interface specification is Closed if we do not want arbitrary customers (of all types) to build products using it, and we do not want others to build alternative implementations. Therefore, specifications for Private interfaces should not be published to customers. Closed interfaces should only be documented to limited internal and external audiences. Note that exposing the source code or participating in an open source project is not considered "publishing a spec". The question is one of intent - do we want others to build dependencies on these interfaces? If so, they should be Open, otherwise they should be Closed.
Consolidation (aka Component)
 A Consolidation is collection of software elements that are always delivered together as a self-consistant entity. Consolidations are reusable, sharable things that form the basis for the complicated software platforms that we deliver. Consolidations are the unit of software that are integrated together to form Products, and are exposed as part of Sun PLC Phase 3 (Develop, Integrate, Test)
 Products are made up of one or more Consolidations; Consolidations are made up of one or more Elements, and Elements evolve over time as Projects are initiated to change them.
 Consolidations let us take advantage of Software Modularity and Reuse - in a very real sense, they are the building blocks that we use to build systems and solutions for our customers.
 Changes are made to consolidations. It is the job of a Gatekeeper to manage the flow of changes as they are integrated into a consolidation. At the beginning, the first change is to create a consolidation. However, once a consolidation exists, it spends the rest of its existance being changed. Bugfixes, code restructuring, performance improvements and the addition of new features all impact the evolution of consolidations. Since a consolidation is presumed to have the means to keep itself self-consistant and to not deliver broken versions of itself, the scope of a Consolidation Private change within a consolidation can be quite large.
 Consolidations do not usually live in isolation - they usually depend on other consolidations, or they do something useful so other consolidations come to depend on them. This dependency introduces a risk - the risk that something you depend upon might change in the future and break your consolidation. Or, more likely, you may wish to do something to your consolidation that might break components that depend on you.
Distribution
 A collection of software arranged for use by others; consists of one or more "consolidations" or "products." Sun's Solaris is one distribution which includes OpenSolaris/ON, JDS/GNome, CDE, Mozilla, Java as well as other consolidations.
Documentation
 This document uses the term "documentation" solely to mean an interface or product description suitable for customers (i.e., those outside Sun who have not signed nondisclosure agreements, but have purchased our products or perhaps accepted free Sun software). The terms "product documentation" or "customer documentation" are often used to stress this meaning.
Element
 The persistant thing that remains in a component as a result of making a change. The term is not a formal definition, but it exists so that we don't have to overload the term "project" to mean both the ephimeral process of making a change and the artifacts that remain as the result of making such a change.
Interface Change
 This document defines a "change" to an interface to include both compatible addition and incompatible change. Except for Project Private, Consolidation Private, and Internal interfaces, all interface changes must be ARC reviewed and approved. A compatible addition is normally permitted in a minor (X.Y) release; adding features in a micro (X.Y.Z) release, or in patches makes it hard for ISVs to determine when they can start depending on the existance of a new feature.
Incompatible change
 A change to an interface or its implementation is incompatible if it can render previously valid programs invalid. "Valid" does not cover programs which depend on unspecified "artifacts of the implementation". A bug fix or performance decreases, in extreme circumstances, could be an incompatible change. The taxonomy describes the minimum release requirements for an incompatible change to an interface. (Sometimes, a new interface can be offered without removing the old one; that would not be incompatible by this definition.)
Partner
 A company, that builds a product that works with and complements Sun products, with whom we have a formal contractual relationship.
Private
 An interface specification that is private to a group can be changed in incompatible ways by coordinating such change only within the group. No other groups need be contacted when making such an incompatible change. The descriptions in this document note whether the various flavors of Private interface require architectural review.
 Note that a Private interface might still be visible to or accessible by other groups. Of course, use of interfaces private to another group carries great stability risks, so ARCs do not normally allow a project to use another's private interfaces.
 Private is different than "secret". An interface would be "secret" if (some) others are *not allowed* to learn about and use the interface. Sun Private interfaces are probably "secret".
 An otherwise-Private interface is "Internal" (the last classification in this document) if others are (physically or practically) *unable* to use it. Therefore, there are several flavors of Private interfaces, depending on who *may* use it; but only one flavor of Internal.
Product
 Software Products are components we provide to customers. We typically sell them for revenue and support them. But, because of the wide association with Sun's good name, software provided to customers for free could still be termed a product. Such software could be made available to download (e.g., over the Internet), or might be shipped as a "free" bonus with another product.
 None of the obvious definitions for "product" is an exact fit. A CD is a product, except that some CDs contain multiple products. A price list item is a product, except that multiple stocking units (SKUs) correspond to the same release of the same product (e.g., basic product, right-to-use, educational price). Some products contain other components that may also be available as separate products (e.g., Solaris Workgroup Server includes Solstice Backup and Solstice AdminSuite products).
 A product release (often merely called a release) is a specific version of a product, such as Solaris Backup 4.2. See "Major, minor, and micro product releases" definitions below.
Project
 A project is an atomic addition or change to Sun's product components (typically software, but possibly hardware, documentation, etc.). A product is made up of one or more projects. A project may depend on other projects, and others depend on it.
 The term "project" is sometimes used to refer to the SDF Implementation Team (I-Team), though "project team" is preferred.
 Note that even when an ARC approves a project, the project is still unsuitable for other projects to depend on. Until a Steering Committee approves the Project's Plan, the project does not have a commitment to a specific tradeoff of functionality, schedule, resources, and quality.
Consolidation
 Software components that are built and delivered together. Products are often composed of multiple consolidations; for example, Solaris has an OS/Net ("ON") consolidation, the Open Windows ("OW") and/or CDE consolidation, Admin consolidation, and others (Platform Support, Diag, Docs, L10n, Graphics?). For very complex products, we bundle multiple Consolidations together to make a "Wad of Stuff" (WOS), also known as a W-Consolidation.
 Developer Products delivers various compilers and tools (sold and licensed separately and in various combinations) on a single installation medium, which allows their cross-product consolidation(s) to avoid inter-product version incompatibility for their Consolidation Private interfaces.
Import and Export
 This document doesn't use the terms Import and Export, but ARC opinions list the interfaces of a project, along with the stability classification from this Taxonomy, sorted by Import or Export.
 The project that defines an interface is said to "export" it, and other projects that can use the defined interface but cannot add to or modify it are said to "import" it. In particular, note that it is not critical which project produces data in a particular format, and which consumes it. For example, a file format may be defined by the project that writes it (e.g., a log file) or reads it (e.g., a Makefile).
End of Feature (EOF) policy
 Before removing a committed feature from the system, a project must first reclassify the feature or interface as Obsolete (see below) and warn customers. After those steps, a later project can actually remove the feature, but not before a period of one year from the customer warning. Both projects must be ARC approved.
Major, minor, and micro product releases; and patches
 A major release is versioned with a .0 suffix (form x.0 or x.0.0), such as 2.0 or 11.0. A minor release has a nonzero suffix (form x.Y or x.Y.0 for nonzero Y), such as 2.1 or 3.12. Changes suitable for a minor release may also be made in a major release. A micro release has two suffixes (form x.y.Z for nonzero Z), such as 1.0.1 or 11.3.2. Changes suitable for a micro release may also be made in a major or minor release. See the Release Taxonomy for more information.
 Most interfaces do not have version numbers. And we do not release "interfaces"; we release products that include Consolidations that contain Elements that export interfaces (and import other interfaces). An incompatible change to a Committed interface, if allowed at all, would require a Major Consolidation release. The ARC opinion approving the project to make the incompatible change would say (in Section 2, Decision and Precedence Information): This project is suitable for delivery in a major release of <consolidation name>.
Interface versioning
 If an interface's producer and consumer are not always built and delivered in unison, the interface should generally be versioned by adding version numbers that are exchanged between the parties. Versioning an interface allows an interface incompatibility to be detected. A multi-part version number (akin to the product release versioning above) is recommended. Sometimes, a fall-back to an earlier interface level (common between the provider and the consumer) is possible. For example, a client newer client attempts to speak protocol 1.1, but a down-rev server answers that it can only handle 1.0, so the client must limit itself to that compatible subset. It has often been helpful for *both* ends to know the version number of the other end, so they can adapt appropriately.
 Interface version numbers do not undergo a major or minor increment merely because the product that ships it does so.

Implementation

Conformance

Exemptions

Contracted Stability Levels
 Exceptions to the terms of a classification are allowed in the form of a "contract" between the provider and consumer of the interfaces. See the Policy Details for more information.
Violating existing stability expectations
 Although being absolutely stable tends to be good thing for isotopes, relationships and interfaces, there are times when it is in the best interest of both the supplier and consumer to break a stability commitment. The following is a list of situations where the ARCs have allowed projects to violate an interface stability commitment: 

• 
  
  1. Security holes where the vulnerability is inherent in the interface.
  2. Data corruption (silent or otherwise) where the vulnerability is inherent in the interface.
  3. Standards violations uncovered by a change in interpretation or enhancement of conformance tests.
  4. An interface specification which isn't controlled by the final implementation provider has been changed incompatibly and the vast majority of interface consumers expect the newer interface.
  5. Not making the incompatable change would be incomprehensible to our customers. One example of this would to have not incompatably changed pcfs when Microsoft abandoned the 8.3 naming restrictions.
      Incompatible changes allowed by exception should always be delivered in the "most major" release vehicle possible. However, often the consequences of the vulnerabilities or contractual branding requirements will force delivery in a patch.
      Every effort should be made to provide prominent and clear notification to the interface consumers as far in advance of the change as is possible and it may be appropriate to provide "impact mitigation" tools.
      A process note is that it should be a rare case where an exception to the interface stability commitment level is approved through a fast-track review. Even if the need is obvious and non-controversial it is valuable that the opinion record the rationale to increase the available precedent information available.

Appeals

CaseHistory

ManPages

References

 All incompatible changes should be carefully considered and reconsidered. Alternatives that keep backward compatibility should be explored. In the past, simply asking engineers to use their best judgement and consider backwards compatibility did not achieve adequate compatibility. Some poor decisions were made and customers were greatly dissatisfied. The ARC process, and interface stability classifications in particular, attempt to prevent such errors from being made in the future. Key process steps are: 

• establish the commitment,
• articulate the commitment (in the ARC review),
• (the ARC and the developers) review the interface and commitment, and
• record the approved commitment (in the SAC archives and on the ARC opinion).
• Then publish the commitment to customers.
   Having established a commitment, we strive to live within its boundaries in subsequent projects by carefully considering the consequences of any incompatible change and by setting customer expectations via product release numbering. Though an interface has a stability level that "allows" incompatible change in a certain level of release, the ARC will review a justification of a proposed incompatible change, to ensure that the positive effects of the incompatibility outweigh the negative for customers.
   As a sweeping generalization, Sun intends to make more functionality more stable over time. Downgrading stability classifications is retracting a commitment, and is normally not normally permitted unless the interface is being reclassified as Obsolete. This process is described under the classification "Obsolete" below.
  Customer Documentation of Interface Stability
   Solaris 2.6 created an ATTRIBUTES section near the end of each manpage, with a table that can include a brief "Stability Level". One of the few manpages that has done so in Solaris 2.6 is ufsdump(4), which says:

{{{___________________________________}}}
| ATTRIBUTE TYPE |  ATTRIBUTE VALUE|
|{{{___________________________________}}}
| Stability Level|  Uncommitted    |
|{{{________________}}}|{{{_________________}}}|

utility name & command line options	Committed
Attribute=Value output format		Committed
reported attributes			Uncommitted
diagnostic messages			Not-An-Interface

 The attributes(5) manpage explains the attributes, including the (Open) Stability Levels which might appear on external manpages, and which set expectations for what kinds of changes are likely to be introduced into what types of release. These explanations include some legal "wiggle room," so they may appear more lax than this document; this document should be assumed authoritative.
 If a project team is unwilling to accept these standard boilerplate commitments, the team must obtain an ARC-approved exemption and ensure that the proposed documentation will adequately set customer expectations.
 White papers, user's guides, or other documentation describing interfaces must also include stability classifications. These documents should either explain Sun's stability classifications using the text Legal already approved or reference the attributes(5) manpage (from Solaris 2.6 or later or on docs.sun.com).

PolicyChangeLog