Audience The intended audience of this document is Sun developers and ARC members in particular. Project teams typically propose to the ARC a stability classification for each of their new or changed interfaces. ARC Opinions identify the stability classification determined by the committee for each interface. Stability classifications from this document should be uniformly spelled with initial capitals, to differentiate them from the common English words. Managers of developers and Steering Committee members (and any others who need to read ARC Opinions) also need to understand the concepts in this classification scheme. Policy * All Software Interfaces must be classified according to this taxonomy. Interfaces are defined as APIs, Files and Directory structures, File formats, Protocols, and (sometimes) even performance and reliability behaviors. * Details +----------------------------------------------------------------------------------------------------+ | Standard | |----------------------------------------------------------------------------------------------------| | | Specification | Open | | |---------------------+--------------------------------------------------------------------------| | | Incompatible Change | major release (X.0) | | |---------------------+--------------------------------------------------------------------------| | | Compatible Change | minor release (x.Y) | | |---------------------+--------------------------------------------------------------------------| | | ARC review of Specs | A precise reference is normally recorded | | |---------------------+--------------------------------------------------------------------------| | | Examples | POSIX, ANSI-C, ABI, SCD, SVID, XPG, X11, DKI, VMEbus, Ethernet, NFS | | | | protocol, DPS | +----------------------------------------------------------------------------------------------------+ Most of these interfaces are defined by a formal standard, and controlled by a standards organization. Incompatible changes to these interfaces are rare. This stability classification can also apply to interfaces that have been adopted (without a formal standard) by an "industry convention" (X/Open, MIT X-Consortium, OMG), or even by a single-source (Adobe's Display PostScript, Novell's NetWare Protocols, Legato's network backup protocols, Berkeley's sendmail) if we expect that the de facto standard is unlikely to change incompatibly. If possible, there should still be a reference to a standard specification or reference system ... although there may be cases where no such citation is possible. Customers are normally pointed to the same specification. Support is only provided for specific version(s) of a standard, and support for a particular version does not guarantee that support will be provided for other versions. Sometimes bugs are corrected or interpretation is clarified in a standard; we may make incompatible changes to react to these, but will evaluate the impact of doing so and will announce a compatibility and migration strategy. (PSARC/1995/224's Advisory Information section provides guidelines for implementing a preliminary draft of a new standard.) Some standards lack bindings to a specific programming language; if the project team chose names, numbers, extensions, or other implementation-specific details, they should be called out for architectural review. ----------------------------------------------------------------------------------------------------------- +----------------------------------------------------------------------------+ | Stable (formerly "Public") | |----------------------------------------------------------------------------| | | Specification | Open | | |---------------------+--------------------------------------------------| | | Incompatible Change | major release (X.0) | | |---------------------+--------------------------------------------------| | | Compatible Change | minor release (x.Y) | | |---------------------+--------------------------------------------------| | | ARC review of Specs | Yes | | |---------------------+--------------------------------------------------| | | Examples | cc options, Sbus, XGL API; most bundled commands | +----------------------------------------------------------------------------+ We publish the specification of these interfaces, typically as manual pages or other product documentation. We also tell customers we will remain compatible with them. (Scott's principle #12: "Compatibility is a constraint, not a goal.") The intention of a Stable interface is to enable arbitrary third parties to develop applications to these interfaces, release them, and have confidence that they will run on all minor releases of the product (after the one in which the interface was introduced, and within the same major release). Even at a major release, incompatible changes are expected to be rare, and to have strong justifications. Sun often proposes Stable interfaces to be industry Standards, as was the case with ToolTalk (now X/Open's). An ARC should review and archive the specification, and adequate customer documentation must also exist. These are interfaces whose specification is generally under Sun's control. +----------------------------------------------------------------------------------------------------+ | Evolving (formerly "Uncommitted", but so was what is now "Unstable") | |----------------------------------------------------------------------------------------------------| | | Specification | Open | | |---------------------+--------------------------------------------------------------------------| | | Incompatible Change | minor release (x.Y), with impact assessment | | |---------------------+--------------------------------------------------------------------------| | | Compatible Change | minor release (x.Y) | | |---------------------+--------------------------------------------------------------------------| | | ARC review of Specs | Yes | | |---------------------+--------------------------------------------------------------------------| | | Examples | core and .il file formats, Solaris DDI & DGA; many GUIs, admin utils, | | | | config files, daemons; most of PAM | +----------------------------------------------------------------------------------------------------+ An Evolving interface is subject to incompatible change at a major or minor release, but we should expect to change an Evolving interface only carefully, and probably slowly. As the interface evolves, we will make reasonable efforts to ensure that all changes are source and binary compatible. An ARC should review the interface specification (especially with respect to ability to absorb expected evolution compatibly). Adequate customer documentation should also exist. The intention of an Evolving interface is to enable ISV's to exploit new technology, and it should be expected that they will ship products that depend on these interfaces. As a result, any incompatible change to an Evolving interface requires an assessment of potential customer impact, and a notification and migration plan. Elements of such a plan might include: * 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. +--------------------------------------------------------------------------+ | Unstable (formerly "Uncommitted", but so was what is now "Evolving") | |--------------------------------------------------------------------------| | | Specification | Open | | |---------------------+------------------------------------------------| | | Incompatible Change | minor release (x.Y) | | |---------------------+------------------------------------------------| | | Compatible Change | micro release (x.y.Z) | | |---------------------+------------------------------------------------| | | ARC review of Specs | Yes | | |---------------------+------------------------------------------------| | | Examples | SUNW* package abbreviations, some config utils | +--------------------------------------------------------------------------+ Unstable interfaces 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. No claims are made about either source or binary compatibility from one minor release to the next. The intention of an Unstable interface is that they be imported only by prototypes and by products on the same CD (or whatever release medium) as the interface implementation. A project's intention to import an Unstable interface 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 Unstable interface should explain why it is acceptable. Any documentation for an Unstable 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 Unstable interfaces in White Papers rather than in standard product documentation. Given such caveats, customer impact need not be a factor when considering incompatible changes to an Unstable interface in a major or minor release. Nonetheless, when such changes are introduced, the changes should still be mentioned in the release notes for the affected release. An ARC should review and archive the specification. Any proposed change to the interface must be ARC approved. 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 Unstable. The interface should be reclassified Standard when standard is final. Such an intention could be encoded "Unstable->Standard".) +--------------------------------------------------------------------+ | External | |--------------------------------------------------------------------| | | Specification | Open | | |---------------------+------------------------------------------| | | Incompatible Change | micro release (x.y.z) | | |---------------------+------------------------------------------| | | Compatible Change | micro release (x.y.z) | | |---------------------+------------------------------------------| | | Arc review of Specs | A precise reference is normally recorded | | |---------------------+------------------------------------------| | | Examples | Freeware | +--------------------------------------------------------------------+ These interfaces are controlled by a body outside of Sun, but unlike Standard, it can not be asserted that an incompatible change to the interface would be exceedingly rare. In some cases it may not even be possible to clearly identify the controlling body. This classification is typically used for community software, freeware, open source and the like. Use of the External interface stability level allows freeware interfaces provided by Sun to quickly track the fluid, external specification. In many cases, this is preferred to providing additional stability to the interface, as it tends to track the expectations of the community. Generally, ancillary characteristics of External interfaces (such as documentation) should adhere more closely to the expectations of the user community than to Sun internal standards. However, External interfaces should adhere to Sun internal standards in the following areas: * 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 | |----------------------------------------------------------------------------------------------------| | | Specification | Open, along with warning of obsolescence | | |---------------------+--------------------------------------------------------------------------| | | Incompatible Change | minor release (x.Y) | | |---------------------+--------------------------------------------------------------------------| | | Compatible Change | By former classification, but unlikely | | |---------------------+--------------------------------------------------------------------------| | | ARC review of Specs | Normally downgraded from a higher stability; ARC approval of interface | | | | or feature removal is also required. | | |---------------------+--------------------------------------------------------------------------| | | Examples | RFS, System-V LP protocol | +----------------------------------------------------------------------------------------------------+ An interface that is "deprecated" and/or no longer in general use. An existing interface may be downgraded from some other status (such as Stable or Standard) to Obsolete to encourage customers to migrate from that interface before it will be removed (or incompatibly changed). In addition to reclassifying the interface Obsolete and documenting the new classification in customer documentation, a pro-active program to communicate to customers the change in commitment must precede the incompatible change or removal in a minor release. For some interfaces, the ARC may find such a communication program appropriate before removing an interface, even at a major release. The standard program to communicate a change in commitment requires: 1. Demonstration of support by the Steering Committee 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 Sun 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 "engineering@sun" used to be considered the standard means of providing notice to the Sun product development community, but that alias has been relegated to being simply "a list of people in the .eng.sun.com NIS domain" for some years now. A better alias (maintained by SAC Staff) is all-smi-engineering@sun.com The notice of obsolescence is considered to be "public" information in that it is 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 released after . Please notify your support person. See in 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. 4. Information in the User Documentation that contains the following: * An explanation of the meaning of Obsolete. * An indication of the kinds of warning messages that may appear. * A suggesting that the customer ask their support person to contact the vendor of any application that causes such a warning to appear. * General instructions for turning off the warning messages. * 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 Steering Committee 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. ----------------------------------------------------------------------------------------------------------- +---------------------------------------------------------------------------+ | Committed Private | |---------------------------------------------------------------------------| | | Specification | Closed | | |---------------------+-------------------------------------------------| | | Incompatible Change | major release (X.0) | | |---------------------+-------------------------------------------------| | | Compatible Change | micro release (x.y.Z) | | |---------------------+-------------------------------------------------| | | ARC review of Specs | Yes | | |---------------------+-------------------------------------------------| | | Examples | UFS media format, Calendar Manager RPC protocol | +---------------------------------------------------------------------------+ For some otherwise-private interfaces, we must maintain compatibility from release to release, in order to meet the customer's expectations for compatibility of the programs using these interfaces. However, we don't want customers to depend on these interfaces directly, and we don't want to directly expose these interfaces to customers. These interfaces are classified as Committed Private. Our commitment is that a customer's "normal" use of system facilities should not allow them to see any incompatible changes to these interfaces. Since these interfaces typically span machines by being embodied in media or protocols (and since customers cannot upgrade all their machines simultaneously), these interfaces can't be changed with the freedom of a private interface. Yet, changes to the details of the interface can be dramatic, provided the commitment to the customer is maintained. In general, Committed Private interfaces should be versioned. An ARC should review and archive the specification, and will at least assure that the interface can satisfy its purpose and support the evolution described in the previous paragraph. Any proposed change to or new dependency on the interface must be ARC approved. Contracted Committed Private This stability level is the same as Committed Private, 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 allow exposure of the interface to a Sun Partner. 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. Partner Private This stability level is no longer in use. Interfaces previously classified as Partner Private should be treated according to the closest matching stability level in the current taxmonomy, probably either Contracted Consolidation Private or Contracted Project Private, depending on the stability of the interface outside of the contract. +-------------------------------------------------+ | Sun Private | |-------------------------------------------------| | | Specification | Closed | | |---------------------+-----------------------| | | Incompatible Change | minor release (x.Y) | | |---------------------+-----------------------| | | Compatible Change | micro release (x.y.Z) | | |---------------------+-----------------------| | | ARC review of Specs | Yes | | |---------------------+-----------------------| | | Examples | trap 40 (gethrtime) | +-------------------------------------------------+ These are interfaces which one consolidation depends on and another consolidation provides. Changes to these interfaces must be coordinated among all providers and users of the interface. Some internal kernel interfaces are Sun Private interfaces. Interfaces are occasionally made Sun Private in order to gain some experience with them before opening them up to wider use as Unstable or Stable interfaces. Making such interfaces Consolidation Private would be preferable, however, as evolution is then far easier. Sun Private interfaces are strongly discouraged. Coordinating changes to these interfaces within a consolidation is usually feasible, but coordinating changes among different consolidations released asynchronously is extremely difficult. Interface versioning is advised for Sun Private interfaces. An ARC will review and archive these interfaces, with special attention to how the interface could evolve, if necessary. Any proposed change to the interface must be ARC approved. Contracted Sun Private This stability level is the same as Sun Private, 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 allow exposure of the interface to a Sun Partner. 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. +------------------------------------------------------------------+ | Consolidation Private | |------------------------------------------------------------------| | | Specification | Closed | | |---------------------+----------------------------------------| | | Incompatible Change | micro release (x.y.Z) or "jumbo patch" | | |---------------------+----------------------------------------| | | Compatible Change | micro release (x.y.Z) or "jumbo patch" | | |---------------------+----------------------------------------| | | ARC review of Specs | Not necessary | | |---------------------+----------------------------------------| | | Examples | libdeskset, kernel nameslists | +------------------------------------------------------------------+ These are interfaces internal to the consolidation that one piece of a consolidation depends on and another piece of the same consolidation provides. Changes to these interfaces must be coordinated among all providers and users of the interface. Many internal kernel interfaces are Consolidation Private interfaces. Generally these are interfaces that have proven convenient for building the consolidation, but which change often enough that we're not willing to document them for external use nor to commit to their stability. libdeskset is an example of such an interface. Though the libkvm API is Public, the undocumented names that can be accessed through that interface are Consolidation or Project Private. An ARC may review and archive these interfaces, or may leave the consolidation to monitor their own internal commitments. If a Consolidation Private interface is reviewed by the ARC, ask that ARC if they want to review later changes to that interface. Importing the interface by any project outside the Consolidation would require negotiating a "contract" with the interface providers. An ARC must review and approve the classification change to Contracted Consolidation Private and the terms of the contract. Contracted Consolidation Private (formerly Contract Private, but so was what is now Contracted Project Private) This stability level is the same as Consolidation Private, 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 allow exposure of the interface to a specific consumer in a different consolidation. 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. Contract Private This stability level is no longer in use, but was in use for many years. Interfaces previously classified as Contract Private should be treated according to the closest matching stability level in the current taxmonomy, probably either Contracted Consolidation Private or Contracted Project Private, depending on the stability of the interface outside of the contract. +----------------------------------------------------------------------------------------------+ | Project Private | |----------------------------------------------------------------------------------------------| | | Specification | Closed | | |---------------------+--------------------------------------------------------------------| | | Incompatible Change | micro release (x.y.Z) | | |---------------------+--------------------------------------------------------------------| | | Compatible Change | micro release (x.y.Z) or patch | | |---------------------+--------------------------------------------------------------------| | | ARC review of Specs | No | | |---------------------+--------------------------------------------------------------------| | | Examples | Metamucil ioctls, nfssys system call, uadmin cpu control functions | +----------------------------------------------------------------------------------------------+ Project Private interfaces usually occur when a project must communicate between its components across a boundary in the system. For instance, Metamucil includes several new ioctls to perform operations on UFS filesystems. The Metamucil ufsdump program uses these ioctls. The ioctls are private interfaces since they are intended to be used only by the Metamucil product. If the Metamucil product needs to change these ioctls in the future, they can do so without coordinating with any other projects, since no other projects may use these ioctls. Likewise, the nfssys system call is used to communicate between the kernel- and user-level portions of NFS. Project Private interfaces also occur in libraries where one module needs to call a private routine in another module in the same library. These internal routines have been visible to users of the library (although normally they are named with an underscore prefix to distinguish them as private) only due to deficiencies in our library construction tools (corrected by Solaris 2.5's "symbol-hiding" loader). Also, Project Private interfaces may be provisional or in transition. The uadmin cpu control functions are Project Private because they will change form before appearing as Standard interfaces, and in the meantime we don't want anyone depending on them. Sadly, many kernel procedures are Project Private interfaces (instead of Internal interfaces) because they are visible to dynamically loaded kernel modules. Once an interface is classified Project Private by an ARC, changes to that interface need not be ARC approved. Any use of the interface from outside the project would involve negotiating a "contract" with the interface providers; an ARC must review and approve the classification change to Contracted Project Private and the terms of the contract. Contracted Project Private (formerly Contract Private, but so was what is now Contracted Consolidation Private) This stability level is the same as Project Private, 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 allow exposure of the interface to a specific consumer in a different consolidation. 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. +---------------------------------------------------------------------------+ | Internal | |---------------------------------------------------------------------------| | | Specification | None (or solely internal to the project) | | |---------------------+-------------------------------------------------| | | Incompatible Change | micro release (x.y.Z) | | |---------------------+-------------------------------------------------| | | Compatible Change | micro release (x.y.Z) or patch | | |---------------------+-------------------------------------------------| | | ARC review of Specs | No ("don't ask, can't tell") | | |---------------------+-------------------------------------------------| | | Examples | procedures internal to any program (not in lib) | +---------------------------------------------------------------------------+ Internal interfaces are not visible by any means to customers -- or anyone outside the project's build -- without source code. Library interfaces, system calls, network protocols, and file formats cannot be internal interfaces. Internal interfaces need not be reviewed or classified by an ARC. ----------------------------------------------------------------------------------------------------------- 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 Stable and/or Standard interfaces (which are unlikely to be changed incompatibly), Evolving, and Unstable 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 ----------------------------------------------------------------------------------------------------------- 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 them 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 the 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. 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. 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; features are not normally added in a micro (X.Y.Z) release, nor in patches. 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 C-Consolidations together to make a "Wad of Stuff" (WOS) 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 SAC release taxonomy in http://sac.eng/BestPractices/release_taxonomy.html Most interfaces do not have version numbers. And we do not release "interfaces"; we release products that include projects that export interfaces (and import other interfaces). An incompatible change to a Stable interface, if allowed at all, would require a Major product 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. 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. ----------------------------------------------------------------------------------------------------------- Policy Implementation Projects are expected to document all "non-Internal" interfaces in their ARC reviews, and, where apropriate, cause their man pages to contain this information as well. ----------------------------------------------------------------------------------------------------------- Policy Conformance The project materials submitted for ARC approval must contain this information. ARC approval will not be granted without this information. ----------------------------------------------------------------------------------------------------------- Policy 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. To indicate this, the word "Contracted" may precede any of the stability levels below. This is most commonly used for "Contracted Consolidation Private", when an interface is considered Consolidation Private but a consumer in a separate consolidation must import that interface via the terms in a contract. Contracted stability levels may be used to describe special arrangements made with Sun Partners by naming the Partner, as well as the Sun employee managing the relationship with that Partner, in the contract. Care should 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 cost us less in the long run. ----------------------------------------------------------------------------------------------------------- Appeals Discuss at your project's ARC review. ----------------------------------------------------------------------------------------------------------- CaseHistory +------------------------------------------------------------------------------------------------------+ | Case | Type | Opinion | Name | One Pager | Comment | |----------------+-----------+---------+-----------------+-----------------------------+---------------| | PSARC/1992/021 | Unknown | Opinion | | | Contract | | | | | | | Private | |----------------+-----------+---------+-----------------+-----------------------------+---------------| | | | | "Obsolete" | | | | PSARC/1993/226 | OnePager | Opinion | Interface | 19930323_peter.vanderlinden | Obsolete | | | | | Taxonomy | | | | | | | addition | | | |----------------+-----------+---------+-----------------+-----------------------------+---------------| | | | | Improvement of | | | | PSARC/1994/084 | FastTrack | | Obsolete | 19940211_steve.chessin | Improved | | | | | classification | | Obsolete | | | | | | | | |----------------+-----------+---------+-----------------+-----------------------------+---------------| | | | | Committed | | | | | | | Private | | Committed | | PSARC/1994/167 | FastTrack | | interface | 19940408_bill.shannon | Private | | | | | classification | | | | | | | | | | |----------------+-----------+---------+-----------------+-----------------------------+---------------| | | | | | | Deprication | | | | | ACL support for | | of Permanent, | | LSARC/1993/100 | FastTrack | Opinion | dump and | 19930204_sam.falkner | Add notation | | | | | restore | | on Import, | | | | | | | Export | |----------------+-----------+---------+-----------------+-----------------------------+---------------| | | | | PC Share | | Clarification | | PSARC/1995/347 | OnePager | None | Reservation | 19951026_david.robinson | of Contract | | | | | Fcntl Interface | | Private | | | | | | | | |----------------+-----------+---------+-----------------+-----------------------------+---------------| | | | | Publishing | | Stable, | | PSARC/1995/351 | FastTrack | Opinion | Commitment | 19951027_mark.kampe | Evolving, and | | | | | Levels | | Unstable | |----------------+-----------+---------+-----------------+-----------------------------+---------------| | PSARC/1998/001 | OnePager | None | Partner-Private | 19980105_mark.kampe | Partner | | | | | Interfaces | | Private | |----------------+-----------+---------+-----------------+-----------------------------+---------------| | | | | External | | | | PSARC/2001/313 | FastTrack | | Interface | 20010424_joseph.kowalski | External | | | | | Taxonomy | | | |----------------+-----------+---------+-----------------+-----------------------------+---------------| | | | | Contracted | | Contracted | | PSARC/2001/421 | FastTrack | | Stability | 20010619_andy.rudoff | Stability | | | | | Levels | | Levels | +------------------------------------------------------------------------------------------------------+ ----------------------------------------------------------------------------------------------------------- ManPages +--------------------------------------------------------------------------+ | Document | Description | |---------------+----------------------------------------------------------| | attributes(5) | Solaris 6 added support for documenting stability levels | +--------------------------------------------------------------------------+ ----------------------------------------------------------------------------------------------------------- References Widespread application of these stability classifications allows us to create software that will reliably continue to function correctly on subsequent minor releases of the operating system (or other asynchronously-delivered software with which it interoperates). This requires that the software, particularly our unbundled software, does not depend on interfaces with inappropriate risk of instability. Publication of these stability classifications to our customers allows developers outside Sun to do the same. Of course, we must also avoid incompatible changes that renege on our commitments. (Scott's principle Number 12: Compatibility is a constraint, not a goal.) All incompatible changes should be carefully considered and reconsidered. Asking all engineers to use their best judgement and consider backwards compatibility did not historically 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: 1. establish the commitment, 2. articulate the commitment (in the ARC review), 3. (the ARC and the developers) review the interface and commitment, and 4. record the approved commitment (in the SAC archives and on the ARC opinion). 5. Then we will publish the commitment to customers. Having established the commitment, we live within its boundaries in subsequent projects by carefully considering the consequences of any incompatible change and set 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 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| Unstable | |________________|_________________| As projects edit manpages, they must determine stability classification(s), get ARC approval, and reflect those stabilities on the manpages. If a manual page describes multiple interfaces with different stabilities, these should all be spelled out. For example: utility name & command line options Stable Attribute=Value output format Stable reported attributes Evolving diagnostic messages Unstable The attributes(5) manpage explains the attributes, including the (Open) Stability Levels which might appear on external manpages, and sets 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 appear more lax than this document; this document should be assumed authoritative. If a team is unwilling to accept the standard boiler plate 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).