Obsolete and the EOF process

Obsolete and the EOF process

Copyright 1991-2007, Sun Microsystems, Inc

Policy Synopsis

This document summarizes all the policies to date on the Obsolete and the End-of-Feature (EOF) process. Note that there is an additional consolidation-specific set of processes that govern how to archive the source code that is being removed.

Contents

• Applicability
• Audience
• Background
• Policy
• Advice
• Glossary
• Conformance
• Exemptions
• Appeals
• CaseHistory

Overview

Applicability

Projects that would like to deprecate and/or remove Standard, Stable, Evolving or Unstable interfaces from a product in a Minor release. 

Audience

PAC members, ARC members, Project Teams 

Background

A 1993 project review by PSARC resulted in a new SAC interface taxonomy classification, Obsolete, so that interfaces with discontinued use can be retired (removed) from the system without requiring a major release. 

Policy

• Applies to All SMI Products
• Authority Rob Gingell
• Approval SAC
• Effective April 1993
• Policy Before removing a committed feature from the system in a Minor release, a project must first
  • reclassify the feature or interface as Obsolete,
  • if feasable, add a warning mechanism that informs the user if/when the interface is used, 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.

• Details

  SAC's interface taxonomy is a scheme used to classify all of the interfaces offered by a project. The interface taxonomy provides a range of values which may be used to identify the commitment level of an interface. The commitment level describes the interface's level of exposure, indicaing who is permitted to use the interface. Present values of the taxonomy are: Standard, Public, Uncommitted, Sun-private, Consolidation-private, Project-private, and Internal.

  The SAC Technical Reference document Interface Taxonomy should be consulted for further details. The section on Obsolete is repeated here:

  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 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.

     A notice of obsolescence is considered to be "public" information in that it is available freely to the customers. It is not intended that this require specific actions to "publish" the information, such as press releases or similar forms of publicity.

  3. Where technically feasible, inclusion in the release where the interface is declared Obsolete of a warning mechanism if the interface is used. The mechanism should produce a message of the form "The application  uses interface  which has been declared obsolete and may not be present in versions of  released after . Please notify your support person. See  in  for more information." One suggested method is to use syslog(3), with a level of "LOG_WARNING". A method for turning off the warning message should also be provided. Common sense should apply in determining how often the warning should appear.
  4. Information in the User Documentation that contains the following:
     • An explanation of the meaning of Obsolete.
     • An indication of the kinds of warning messages that may appear.
     • A suggesting that the customer ask their support person to contact the vendor of any application that causes such a warning to appear.
     • General instructions for turning off the warning messages.
     • A list of the Obsolete interfaces contained in this release, the earliest that they may disappear, the kind of warning that might appear, and the method for disabling the warning.

  Proposals to downgrade an interface through this mechanism must be approved by an ARC before "core" documentation may be altered to identify the interface as Obsolete. Release notes may warn of the possibility of removal with either ARC or Steering Committee approval. (A warning that the interface *may* be removed in a future release could be included without ARC approval, but the ARC may not deem such notice alone as sufficient notification to customers to "start the 1-year clock".)

  A follow-on project to perform the actual feature removal in a forthcoming minor or major release after the timeout period expires, requires architectural approval to ensure that the requirements of the obsolescence policy have been met. Provided they have been met, approval will be straightforward.

Advice

Obsolescence and EOL: SAC Guidelines

 Recently, there's been some confusion about how the SAC policy for removing obsolete interfaces or components from the system works. This article attempts to clear up the confusion. Note that there is a different process for removing obsolete products from a product offering. For a description of that process, please see: EOL Process Diagram (Katy Dickinson, et al).

 The policy described here applies when you wish to remove an obsolete component from the system. There are two steps for doing so. First, reclassify the facility's interfaces as Obsolete. Second, remove the facility. The following paragraphs explain these steps in more detail.

 The first step in removing something from the system is to conduct a project whose aim is to reclassify it as obsolete. The procedure for doing this is stated in the  interface.taxonomy, in the section describing Obsolete interfaces; see it for the details of the process.

 Because customers or internal developers may be depending on the facility you want to remove, the process includes getting ARC approval for lowering the facility's commitment level to Obsolete. The ARC discussion will examine the implications of changing the interfaces to a level where they may subsequently be removed. The ARC will also want to verify that affected parties will be notified well in advance of the removal, so that they have a chance to prepare for it, or to argue with Sun for its continuance.

 Obtaining ARC approval for the change to Obsolete classification must precede any changes to the system that lead to the facility's removal. In particular, it is not acceptable to alter documentation to warn of pending obsolescence before obtaining ARC approval.

 The process also requires a timeout period of one year before removal. During this period, if it is technically feasible to do so, attempted use of the obsolete facility should cause the user attempting the use to get a warning message. This requirement is intended to give people who will be affected by removing the facility a chance to make alternative arrangements before we "yank the rug out" from underneath them.

 If any products contain documentation warnings of an impending interface removal that doesn't have an ARC decision classifying the interface as Obsolete, start a case (probably a fast-track is sufficient) to ratify the commitment level and to insert the runtime warning (if technically feasible).

 After the timeout period expires and you've met the rest of the requirements of the obsolescence policy, you can initiate a follow-on project to perform the actual removal. As with any other change to the system, this project requires architectural approval. The review will ensure that you've actually met the requirements of the obsolescence policy. Provided you've done so, approval will be straightforward.

Glossary

 EOF - End of Feature
 The removal of (a set of) interfaces from a product. See also the current SOE-PAC policy on EOF's.

 Co-Packaged
 Multiple products delivered to the customer as a unit. Co-Packaged products are typically also "Unbundled".

 Bundled
 Components integrated together to make a single product offering, where the components do not have an independent product life of their own.

 Unbundled
 Components that are intended to be delivered to the customer independently from other SMI product offerings. See also "Co-Packaged".

Conformance

All changes in interface stability level must be ARC approved, and all interface removals must also have ARC approval. 

Exemptions

Discuss with ARC during review of Obsolescence case. 

Appeals

Follow the SAC Appeals Process after your ARC case has concluded. 

CaseHistory