Table of Contents
This chapter provides information on standards and procedures which must be followed by all developers. These rules are the same ones which Sun engineers have been required to follow when developing Solaris, and are the primary reason Solaris, and now OpenSolaris, is among the world's best available software. These standards generally apply to all consolidations.
OpenSolaris has a comprehensive set of rules governing interfaces. An interface is any aspect of the system that a user or developer can observe or use. Examples include functions and variables in libraries, the location of a particular executable program, the output content, format, and argument semantics of an executable program, and the location in the filesystem of a header file. There are thousands of interfaces provided by OpenSolaris, and each of them has certain visibility, documentation, and compatibility constraints.
One of the attributes included in many Solaris man pages is "Interface Stability." The value of this attribute defines who may depend on the interface, and what expectations they may have for its future maintenance. The possible values and their explanations are described here; note that the Private levels will not appear in man pages shipped to customers.
In the absence of any evidence about an interface's stability level, certain assumptions must be made. Following the general rule "be strict in what you produce, and liberal in what you accept" would lead one to conclude that any documented interface is Stable, and undocumented interfaces are probably being used by others, but could be changed at any time without your knowledge (i.e. they are at once both Project Private and Unstable); as a consequence you should neither change the interface nor depend on its current implementation. If you need to depend on or change an undocumented interface whose stability level cannot be determined, you need to find that interface's owner, if any, and have the action approved by the relevant ARC. If the owner of the interface can be found, you will most likely want to promote the interface either to Open (public) status, or use one of the Contracted Private stability levels.
Following is a list of stability levels and their respective meanings. Additional information is available in the attributes(5) man page, including the precise public definitions of major, minor, and micro releases and additional information about Open interfaces.
Stability Level: 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.
Stability Level: Stable
---------------------------------------------------------------- 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.
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), without having to change or recompile the applications. Even at a major release, incompatible changes are expected to be rare, and to have strong justifications. Stable interfaces are sometimes proposed to be industry Standards, as was the case with ToolTalk (now an X/Open standard).
An ARC should review and archive the specification, and adequate customer documentation must also exist.
These are interfaces whose specification is generally controlled within OpenSolaris, and does not rely on externally delivered projects.
Stability Level: Evolving
---------------------------------------------------------------- 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. Nonetheless, foreseen promotion is not a necessary attribute of the Evolving taxonomy level. An interface could be classified Evolving and remain as such indefinitely.
Stability Level: Unstable
---------------------------------------------------------------- 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 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".)
Stability Level: 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 OpenSSL ----------------------------------------------------------------
These interfaces are controlled by a body outside of OpenSolaris, 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 third-party open source components integrated wholesale into an OpenSolaris consolidation.
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. However, External interfaces should adhere to OpenSolaris standards in at least 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 we are not in explicit control of the changes, we 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.
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 OpenSolaris. 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 software. It is suggested to use External and behave (through contracts) as Unstable. Use of the Evolving classification promotes these interfaces to first class OpenSolaris interfaces, at the potential cost of diverging from the external specification. By using Evolving, we are essentially taking control of the interface, although it may liberally import from the external reference. Use of the Stable classification is not recommended.
Stability Level: 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.
Stability Level: 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.
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 [event]. Please notify your support person. See in [reference] 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.
Stability Level: Committed Private
---------------------------------------------------------------- Specification Closed ---------------------------------------------------------------- Incompatible Change major release (X.0) ---------------------------------------------------------------- Compatible Change micro release (x.y.Z) ---------------------------------------------------------------- ARC review of Specs Yes ---------------------------------------------------------------- Example 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.
Stability Level: 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.
Stability Level: Sun Private
---------------------------------------------------------------- Specification Closed ---------------------------------------------------------------- Incompatible Change minor release (x.Y) ---------------------------------------------------------------- Compatible Change micro release (x.y.Z) ---------------------------------------------------------------- ARC review of Specs Yes ---------------------------------------------------------------- Example 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.
Stability Level: 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 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.
Stability Level: 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.
Stability Level: Contracted Consolidation 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.
Stability Level: 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.
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.
Stability Level: Contracted Project 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.