Wiki code for Interface Taxonomy

Hide Line numbers
1: ==  Interface Taxonomy
2: 
3: Copyright 1991-2006, Sun Microsystems, Inc
4: 
5: ||**Table of Contents**|**Overview**|**Policy Synopsis**
6: |
7: [[Audience>>#Audience]]
8: [[Background>>#Background]]
9: [[History>>#History]]
10: [[Policy>>#Policy]]
11: [[Advice>>#Advice]]
12: [[Glossary>>#Glossary]]
13: [[Implementation>>#Implementation]]
14: [[Conformance>>#Conformance]]
15: [[Exemptions>>#Exemptions]]
16: [[Appeals>>#Appeals]]
17: [[CaseHistory>>#CaseHistory]]
18: [[ManPages>>#ManPages]]
19: [[References>>#References]]
20: [[PolicyChangeLog>>#PolicyChangeLog]]
21: ||Category|Software
22: |Owner|SAC
23: |Author|ARC-Chairs
24: |Changes|ARC-Chairs
25: |Authority|SAC
26: |Policy Version|3.1
27: |Status|Approved
28: |Last Reviewed|Jun 14, 2006
29:  Dec 5, 2001
30: |Effective|April, 1992
31: |
32: The Interface Taxonomy is a classification scheme for interfaces which is used to ascribe a //stability classification// to an interface.
33: 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.
34: The stability classification identifies:
35: * who may use the interface ~-- that is, the architectural level at which the interface is exposed;
36: * the risk of possible breakage or incompatibility; and
37: * the commensurate constraints on incompatible change to the interface.
38: | |
39: ----
40: == Audience
41:  This document was written for software developers who are managing stability expectations for the components and features they are developing.
42:  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.
43:  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.
44: ----
45: == Background
46:  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.
47:  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).
48:  The interface taxonomy stability classifications in this document may be divided into two broad, distinct groups:
49: ** Public: (Committed, Uncommitted, Volatile, Not-an-interface)
50:  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.
51: ** Private: (Sun Private, Committed Private, Consolidation Private, Project Private)
52:  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.
53: ----
54: == History
55:  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>>#Advice]] presents the classification levels deprecated by this revision and provides mapping details from those deprecated levels to the current levels.
56:  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.
57:  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.
58: |=Old Classification|=New Classification|=Comments
59: |Public |Committed |Name change
60: |Stable |Committed |Name change
61: |Standard |Committed |Include a reference to the controlling specification
62: |Evolving |Committed |[[All ON/PSARC cases>>#EXPSARC]]
63: |Evolving |Uncommitted |[[Except ON/PSARC cases>>#EXPSARC]]
64: |Unstable |Uncommitted |Name change
65: |External |Volatile |Name change with expansion of allowed usage
66: |Obsolete |(Obsolete) |Was a classification, now a modifier
67: |*Private |*Private |Unchanged
68: ** Standard
69:  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.
70:  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.
71:  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.
72: ** Evolving
73:  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).
74:  Within the ARC process, the different ARCs have been applying different interpretations of Evolving which had lead to confusion and conflicting expectations.
75:  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.
76:  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.
77:  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.
78:  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.
79: ** External
80:  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.
81:  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.
82: ** Obsolete
83:  Obsolete was moved from "classification" status to "modifier" status to help regularize the taxonomy. In concept and application it is unchanged.
84: ----
85: == Policy
86: * **Applies to** All software produced by SMI
87: * **Authority** SAC
88: * **Approval** SAC
89: * **Effective** April, 1992
90: * **Policy** 
91: ** 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.
92: ** 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.
93: ** 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.
94: ** 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.
95: * **Details**  === Public Interface Classifications|**Committed** (formerly Stable, Public; encompasses Standard, Evolving)
96: | |Specification| Open
97: |Incompatible Change| major release (X.0)
98: |ARC review of Specs| Yes
99: |Examples| Compiler command line options, hardware interconnects (SBus, PCI, USB...), RPC, POSIX utilities
100:  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 McNealy’s principle that "Compatibility is a constraint, not a goal") The intention of a Committed interface is to enable arbitrary third parties to develop applications to these interfaces, release them, and have confidence that they will run on all 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.
101:  Committed interfaces are often proposed to be industry standards, as was the case with RPC. Also, interfaces defined and controlled as industry standards are most often treated as Committed interfaces.
102:  These are interfaces whose specification is often under the provider’s control or which are specified by a clearly versioned document controlled by a well-defined organization. If the interface specification is not under the implementation provider’s control, the provider must be willing to fork from the interface specification if required to maintain compatibility. In the case of interface specifications controlled by a standards body, the commitment must be to a clearly identified version of the specification, minimizing the likelihood of an incompatible change (but it can happen through formal spec interpretations).
103:  Also, if the interface specification is not under the control of the interface implementation provider, then the controlling body and/or public, versioned document must be be noted in the documentation. This is particularly important for specifications controlled by recognized standards organizations.
104:  Although a truely exceptional event, incompatible changes are possible in any release if the associated defect is serious enough as outlined in the [[EXEMPTIONS>>#Exemptions]] section of this document or in a Minor release by following the End of Feature process.
105: |**Uncommitted** (formerly "Unstable")
106: | |Specification| Open
107: |Incompatible Change| minor release (x.Y), with impact assessment
108: |ARC review of Specs| Yes
109: |Examples| SUNW* package abbreviations, some config utils
110:  No guarantees are made about either source or binary compatibility of these interfaces from one Minor release to the next. The most drastic incompatible change of removal of the interface in a Minor release is allowed. Uncommitted interfaces are generally not appropriate for use by release-independent products.
111:  Uncommitted is not a license for gratuitous change. Any incompatible changes to the interface should be motivated by true improvement to the interface which may include justifiable ease of use considerations. The general expectation is that Uncommitted interfaces are not likely to change incompatibly and if such changes occur they will be small in impact and should often have a mitigation plan.
112:  Uncommitted interfaces generally fall into one of the following subcategories:
113: *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.
114: *1. 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.
115: *1. 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.
116:  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.
117:  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.
118:  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".)
119: |**Volatile** (encompasses External)
120: | |Specification| Open
121: |Incompatible Change| Micro release (x.y.Z) or Patch
122: |ARC review of Specs| A precise reference is normally recorded
123: |Examples| Gimp user interface, IETF internet-draft
124:  Volatile interfaces may change at any time and for any reason.
125:  Use of the Volatile interface stability level allows interface providers to quickly track a fluid, rapidly evolving specification. In many cases, this is preferred to providing additional stability to the interface, as it may better meet the expectations of the consumer.
126:  The most common application of this taxonomy level is to interfaces that are controlled by a body other than the final implementation provider, but unlike specifications controlled by standards bodies or communities we place trust in, it can not be asserted that an incompatible change to the interface specification would be exceedingly rare. In some cases it may not even be possible to clearly identify the controlling body. Although not prohibited by this taxonomy, the Volatile classification is not typically applied to interfaces where the specification is controlled by the implementation provider.
127:  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 separate from the implementor. Use of the Uncommitted 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. Committed should be considered for required, core interfaces. If instability in the interface definition can’t be reconciled with the requirement for stability, then alternate solutions should be considered.
128:  This classification is typically used for free or open source software (FOSS), also referred to as community software, and similar models where it is deemed more important to track the community with minimal latency than to provide stability to our customers. When applying this classification level to community software, particular attention should be paid to the considerations presented in the preceding paragraph.
129:  It also may be appropriate to apply the Volatile classification level to interfaces in the process of being defined by trusted or widely accepted organization. These are generically referred to as draft standards. An "IETF internet draft" is a well understood example of a specification under development.
130:  There may also cases where Volatile is appropriate for experimental interfaces, but in most cases Uncommitted should be considered first.
131:  Irrespective of the control of the specification, the Volatile classification must not be applied to "core" interfaces (those that must be used) for which no alternate (and more stable) interface exists. Volatile interfaces must also adhere to Sun internal standards in the following areas:
132: ** Security, Authentication
133: ** The existence of (perhaps vestigial) Manual Pages and conformance to Sun section numbering
134: ** File System Semantics (Solaris examples: /usr may be read-only, /var is where all significant run-time growth occurs, ...)
135:  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.
136:  Shipping incompatible change in a patch should be strongly avoided. It is not strictly prohibited for the following two reasons:
137: ** 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.
138: ** A strong business case may exist for shipping a newer version as a patch if that newer version closes significant escalations.
139:  In general, the intent of allowing change in a patch is to allow for change in Update Releases.
140:  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.
141:  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.
142: |**Not-an-interface**
143: | |Specification| None
144: |Incompatible Change| Micro release (x.y.Z) or Patch
145: |Arc review of Specs| None
146: |Examples| CLI output, error text
147:  In the course of reviewing or documenting interfaces, the situation often occurs that an attribute will be present which may be inferred to be an interface, but actually is not. A couple of common examples of this are output from CLIs intended only for human consumption and the exact layout of a GUI.
148:  This classification is simply a convenience term to be used to clarify such situations where such confusion is identified as likely. Failure to apply this term to an attribute is no indication that said attribute is some form of interface. It only indicates that the potential for confusion was not identified.
149: === Private Interface Classifications
150: |**Sun Private**
151: | |Specification| Closed
152: |Incompatible Change| minor release (x.Y)
153: |ARC review of Specs| Yes
154: |Examples| trap 40 (gethrtime)
155:  These are stable interfaces which one consolidation depends on and another consolidation provides. As changes to these interfaces must be coordinated among all providers and users of the interface, the expectation is that they are extremely stable. Some internal kernel interfaces are Sun Private interfaces.
156: **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.
157:  Interfaces are occasionally made Sun Private in order to gain some experience with them before opening them up to wider use as Committed interfaces. Making such interfaces Consolidation Private would be preferable, however, as evolution is then far easier.
158:  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.
159: **Contracted Sun Private**
160:  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.
161:  An ARC must 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.
162: |**Committed Private**
163: | |Specification| Closed
164: |Incompatible Change| major release (X.0)
165: |ARC review of Specs| Yes
166: |Examples| UFS media format, Calendar Manager RPC protocol
167:  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.
168:  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 must be versioned.
169:  An ARC must 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.
170: **Contracted Committed Private**
171:  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.
172:  An ARC must 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.
173: **Partner Private**
174:  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.
175: |**Consolidation Private**
176: | |Specification| Closed
177: |Incompatible Change| micro release (x.y.Z) or "jumbo patch"
178: |ARC review of Specs| Not necessary
179: |Examples| libdeskset, kernel nameslists
180:  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.
181:  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.
182:  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.
183:  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.
184: **Contracted Consolidation Private**
185:  (formerly **Contract Private**, but so was what is now **Contracted Project Private**)
186:  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.
187:  An ARC must 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.
188: **Contract Private**
189:  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.
190: |**Project Private**
191: | |Specification| Closed
192: |Incompatible Change| micro release (x.y.Z)
193: |ARC review of Specs| No
194: |Examples| Metamucil ioctls, nfssys system call, uadmin cpu control functions
195:  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.
196:  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).
197:  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.
198:  Sadly, many kernel procedures are Project Private interfaces (instead of Internal interfaces) because they are visible to dynamically loaded kernel modules.
199:  Once an interface is classified Project Private by an ARC, changes to that interface need not be ARC approved.
200:  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.
201: **Contracted Project Private**
202:  (formerly **Contract Private**, but so was what is now **Contracted Consolidation Private**)
203:  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.
204:  An ARC must 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.
205: |**Internal**
206: | |Specification| None (or solely internal to the project)
207: |Incompatible Change| micro release (x.y.Z)
208: |ARC review of Specs| No ("don’t ask, can’t tell")
209: |Examples| procedures internal to any program (not in lib)
210:  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.
211: === Modifiers
212:  Modifiers may prefix a compatibility level to modify its meaning.
213: ; **Contracted**
214: :
215:  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.
216:  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.
217:  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.
218: >  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//.
219:  The other common usage is to allow a Sun product to use an Uncommitted or Volatile interface supplied by another consolidation.
220:  A [[ boilerplate contract form>>Community Group arc.contract]] exists (targeted at interface being Consolidation Private).
221:  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.
222:  Contracts are reviewed, approved and archived by the ARCs just as projects are.
223:  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.
224: ; **Obsolete**
225: :
226:  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).
227:  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.
228: |=Former
229: Classification|=Release Type|=Obsolescence
230: allowed?|=Notification
231: Needed?|=Removal
232: Allowed?
233: |Committed|Major|Yes|Maybe*|Yes
234: |Minor|Yes|Yes|Yes
235: |Micro|Yes|Yes|No
236: |Patch|No |-na-|No
237: |Uncommitted|Major|Yes|No|Yes
238: |Minor|Yes|Maybe*|Yes
239: |Micro|Yes|Yes|No
240: |Patch|No |-na-|No
241: |Volatile|Major|Yes|No|Yes
242: |Minor|Yes|No|Yes
243: |Micro|Yes|No|Yes
244: |Patch|Yes|No|Yes
245:  {{{________}}}
246: 
247:  [*] 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.
248:  {{{________}}}
249: 
250:  The standard program to communicate a change in commitment requires:
251: *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.
252: *1. 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.
253:  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.
254:  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.
255:  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.
256:  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.
257: *1. 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
258: >  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.
259:  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.
260: *1. Information in the User Documentation that contains the following:
261: *1* An explanation of the meaning of Obsolete.
262: *1* An indication of the kinds of warning messages that may appear.
263: *1* A suggesting that the customer ask their support person to contact the vendor of any application that causes such a warning to appear.
264: *1* General instructions for turning off the warning messages.
265: *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.
266:  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".)
267:  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.
268: ----
269: == Advice
270: **Interface Stability Considerations**
271:  When a project team proposes (or an ARC reviews) an interface’s stability classification, consider and discuss with the ARC:
272: ** Who are the desired consumers of the interface? What stability levels will those consumers require?
273: ** What evolution do you envision or even imagine? Does the design of the interface allow sufficient freedom to evolve the interface compatibly?
274: ** 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?
275: ** Assure that product/project documentation sets consumer expectations appropriately.
276: ** 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.
277: ** Maintain and evolve the interface only in manners consistent with its stability classification.
278: **Special Considerations for Libraries**
279:  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.
280:  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.
281:  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>>Community Group arc.bp-libraries]]
282: **Deprecated stability levels**
283: ; Standard => Committed
284: :
285:  The former definition of Standard was:
286: > |**Standard**
287: | |Specification| Open
288: |Incompatible Change| major release (X.0)
289: |ARC review of Specs| A precise reference is normally recorded
290: |Examples| POSIX, ANSI-C, ABI, SCD, SVID, XPG, X11, DKI, VMEbus, Ethernet, NFS protocol, DPS
291:  Most of these interfaces are defined by a formal standard, and controlled by a standards organization. Incompatible changes to these interfaces are rare.
292:  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.
293:  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.
294:  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.)
295:  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.
296: ; Evolving => Committed
297: :
298:  The former definition of Evolving was:
299: > |**Evolving** (formerly "Uncommitted", but so was what is now "Unstable")
300: | |Specification| Open
301: |Incompatible Change| minor release (x.Y), with impact assessment
302: |ARC review of Specs| Yes
303: |Examples| core and .il file formats, Solaris DDI & DGA; many GUIs, admin utils, config files, daemons; most of PAM
304:  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.
305:  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:
306: ** clearly setting customer expectations about the circumstances under which the interfaces might change.
307: ** ensuring that all such changes are described in the release notes for the affected release.
308: ** providing migration aids for binary compatibility and/or continued source development.
309:  A project’s intention to accept the risk of depending on an Evolving interface must be evaluated and explicitly approved by an ARC.
310:  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.
311: ; External => Volatile
312: :
313:  The former definition of External was:
314: > |**External**
315: | |Specification| Open
316: |Incompatible Change| micro release (x.y.Z)
317: |Arc review of Specs| A precise reference is normally recorded
318: |Examples| Freeware
319:  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.
320:  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:
321: ** Security, Authentication
322: ** Manual Page Section Numbering
323: ** File System Semantics (/usr may be read-only, /var is where all significant run-time growth occurs, ...)
324:  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.
325:  Shipping incompatible change in a patch should be strongly avoided. It is not strictly prohibited for the following two reasons:
326: ** Since Sun is not in explicit control of the changes, it can not guarantee with reasonable assurance that an unidentified incompatibility isn’t present.
327: ** A strong business case may exist for shipping a newer version as a patch if that newer version closes significant escalations.
328:  In general, the intent of allowing change in a patch is to allow for change in Update Releases.
329:  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.
330:  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.
331: **Contracted External**
332:  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.
333:  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.
334: ; Obsolete => //Becomes a modifier for other levels, not a level of its own//
335: :
336:  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:
337: > |**Obsolete**
338: | |Specification| Open, along with warning of obsolescence
339: |Incompatible Change| minor release (x.Y)
340: |ARC review of Specs| Normally downgraded from a higher stability; ARC approval of interface or feature removal is also required.
341: |Examples| RFS, System-V LP protocol
342:  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).
343: ----
344: == Glossary
345: **Interface**
346:  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.
347:  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.
348:  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.
349: **Specification**
350:  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.
351: **Open specification:**
352:  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".
353: **Closed specification**
354:  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.
355: **Consolidation (aka Component)**
356:  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)
357:  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.
358:  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.
359:  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.
360:  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.
361: **Distribution**
362:  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.
363: **Documentation**
364:  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.
365: **Element**
366:  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.
367: **Interface Change**
368:  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.
369: **Incompatible change**
370:  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.)
371: **Partner**
372:  A company, that builds a product that works with and complements Sun products, with whom we have a formal contractual relationship.
373: **Private**
374:  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.
375:  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.
376:  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".
377:  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.
378: **Product**
379:  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.
380:  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).
381:  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.
382: **Project**
383:  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.
384:  The term "project" is sometimes used to refer to the SDF Implementation Team (I-Team), though "project team" is preferred.
385:  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.
386: **Consolidation**
387:  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.
388:  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.
389: **Import and Export**
390:  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.
391:  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).
392: **End of Feature (EOF) policy**
393:  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.
394: **Major, minor, and micro product releases; and patches**
395:  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.html>>Community Group arc.release_taxonomy]] for more information.
396:  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//>.//
397: **Interface versioning**
398:  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.
399:  Interface version numbers do not undergo a major or minor increment merely because the product that ships it does so.
400: ----
401: == Implementation
402: ----
403: == Conformance
404: ----
405: == Exemptions
406: **Contracted Stability Levels**
407:  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.
408: **Violating existing stability expectations**
409:  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:
410: *1. Security holes where the vulnerability is inherent in the interface.
411: *1. Data corruption (silent or otherwise) where the vulnerability is inherent in the interface.
412: *1. Standards violations uncovered by a change in interpretation or enhancement of conformance tests.
413: *1. 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.
414: *1. 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.
415:  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.
416:  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.
417:  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.
418: ----
419: == Appeals
420: ----
421: == CaseHistory
422: |=Case|=Type|=Name|=Comment
423: |[[PSARC/1992/021>>Community Group arc.021]]|Unknown|  | Contract Private
424: |[[PSARC/1993/226>>Community Group arc.226]]|OnePager| "Obsolete" Interface Taxonomy addition  | Obsolete
425: |[[PSARC/1994/084>>Community Group arc.084]]|FastTrack| Improvement of Obsolete classification  | Improved Obsolete
426: |[[PSARC/1994/167>>Community Group arc.167]]|FastTrack| Committed Private interface classification  | Committed Private
427: |[[LSARC/1993/100>>Community Group arc.100]]|FastTrack| ACL support for dump and restore  | Deprication of Permanent, Add notation on Import, Export
428: |[[PSARC/1995/347>>Community Group arc.347]]|OnePager| PC Share Reservation Fcntl Interface  | Clarification of Contract Private
429: |[[PSARC/1995/351>>Community Group arc.351]]|FastTrack| Publishing Commitment Levels  | Stable, Evolving, and Unstable
430: |[[PSARC/1998/001>>Community Group arc.001]]|OnePager| Partner-Private Interfaces  | Partner Private
431: |[[PSARC/2001/313>>Community Group arc.313]]|FastTrack| External Interface Taxonomy  | External
432: |[[PSARC/2001/421>>Community Group arc.421]]|FastTrack| Contracted Stability Levels  | Contracted Stability Levels
433: |[[PSARC/2005/220>>Community Group arc.220]]|FastTrack| New Public Taxonomy  | New Public Taxonomy
434: ----
435: == ManPages
436: |=Document|=Description
437: |attributes(5)|Solaris 2.6 added support for documenting stability levels
438: ----
439: == References
440:  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:
441: *1. establish the commitment,
442: *1. articulate the commitment (in the ARC review),
443: *1. (the ARC and the developers) review the interface and commitment, and
444: *1. record the approved commitment (in the SAC archives and on the ARC opinion).
445: *1. Then publish the commitment to customers.
446:  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.
447:  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.
448: **Customer Documentation of Interface Stability**
449:  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:
450: 
451: {{{
452: 
453: {{{___________________________________}}}
454: | ATTRIBUTE TYPE |  ATTRIBUTE VALUE|
455: |{{{___________________________________}}}
456: | Stability Level|  Uncommitted    |
457: |{{{________________}}}|{{{_________________}}}|
458: }}}
459: 
460: {{{
461: utility name & command line options	Committed
462: Attribute=Value output format		Committed
463: reported attributes			Uncommitted
464: diagnostic messages			Not-An-Interface
465: }}}
466: 
467:  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.
468:  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.
469:  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).
470: ----
471: == PolicyChangeLog
472: |=Version|=Date|=By|=Description
473: |3.1  |06/07/26  |plocher  |includes jek3’s changes to the public stability levels:
474: Committed, Uncommitted, Volatile, Not-An-Interface, Obsolete  
475: |2.11  |03/04/23  |plocher  |updated comments re: engineering alias for Obsolete notifications  
476: |2.10  |02/12/04  |plocher  |changed Owner=SAC  
477: |2.9  |02/11/22  |plocher  |Added Owner=SAC to BPs  
478: |2.8  |02/07/27  |plocher  |added Type=Policy  
479: |2.7  |02/07/18  |plocher  |converted to "best practice" format  
480: |2.6  |01/12/05  |andy  |changes from PSARC/2001/313 and PSARC/2001/421  
481: |2.5  |98/05/05  |markk  |eliminate leading blanks  
482: |2.4  |98/05/05  |markk  |corrected a bad line wrap  
483: |2.3  |98/05/05  |markk  |added partner private per 1998/001  
484: |2.2  |97/10/23  |stanton  |Added reference to Solaris 2.6’s attributes(5) manpage.  
485: |2.1  |96/05/06  |stanton  |Bumped version number to reflect important term change
486: (even though it was a few versions back).  
487: |1.18  |96/05/06  |stanton  |Relaxed SPF protection factor with Marty’s approval.
488: All Sun engineers (and probably other Sun employees) need to know.  
489: |1.17  |96/04/25  |stanton  |Added more propoganda about why we bother to establish stability classifications
490: for interfaces; added Considerations from projects, including library projects;
491: changed "Private" back to "Closed" for specifications; added definitions.
492: Evolving I/Fs are not necessarily under Sun’s control or becoming Stable.  
493: |1.16  |96/02/13  |stanton  |Ready for SAC review; still has open issues.  
494: |1.15  |96/01/25  |stanton  |Merged in exactly the text from Mark Kampe (Jan 18, 1996).  
495: |1.14  |95/12/08  |stanton  |Added definition of "Consolodation" (unapproved).  
496: |1.13  |95/02/16  |stanton  |Reacting to someone’s (Glenn’s?) comments ~-- ARC approval is *always*
497: required for non-private interface changes.  
498: |1.12  |94/11/11  |stanton  |Extended discussion of Standard classification to address
499: single-source third-party specifications.  
500: |1.11  |94/11/11  |stanton  |Altered the wording to imply that Permanent is an obsolete classification.  
501: |1.10  |94/11/01  |stanton  |Added Committed Private from PSARC/1994/167, and
502: a note about Permanent from LSARC/1993/100.
503: Also added definitions for Import and Export.  
504: |1.9  |94/05/31  |chessin  |updated to include PSARC/1994/084  
505: |1.8  |94/01/28  |chessin  |put in *real* definition of Obsolete, as approved by PSARC/1993/26;
506: the "summary" lost significant information. Also restored SCCS keywords.  
507: |1.7  |93/06/14  |stanton  |Added Contract Private (per PSARC/1992/021) to Frame and ASCII versions.
508: Arguably needs definition for "import" and "export"
509: since they don’t mean "consume" and "produce" (respectively),
510: but something closer to "utilize" and "define".  
511: |1.6  |93/06/14  |stanton  |Updated to match Frame "it.doc" version 1.1 by adding Obsolete,
512: approved as PSARC/1993/226. Still needs addition of Contract Private,
513: approved with PSARC/1992/021.  
514: |1.5  |92/09/03  |shannon  |final approved version was never checked in  
515: |1.4  |92/04/21  |lhatt  |removed header and renamed file to interface.taxonomy  
516: |1.3  |92/04/14  |lhatt  |Integrate changes from Bill Shannon.  
517: |1.2  |92/04/14  |lhatt  |Changes from product to consolidation.  
518: |1.1  |92/04/14  |lhatt  |CodeManager Uniquification: doc/interface.taxonomy/interface.taxonomy.txt
519: date and time created 92/04/14 09:56:00 by lhatt  
520: |
OpenSolaris

Top Menu

Wiki code for Interface Taxonomy

Search

Collectives

Community Group

Project

User Group

Subsites

Community Group arc Pages
