Revision as of 13:33, 12 May 2010

NOTE: This page is a work in progress and may evolve or radically change before it is finalized. Sections have been adapted from WTP_API_Policy

API availability has typically varied across projects in Linux Tools. With the recent push to standardize data collection and UI API's, however, a more stringent API policy should be enforced.

Declared API

Declared API is API that maintainers of Linux Tools projects have declared as intended for outside use. API can only be given Declared status by the maintainer of each project, or by the Linux Tools project lead. Declared API represents a commitment on behalf of the maintainers to an API that will be frozen by time of release and will not change throughout the remainder of the release or in corresponding maintenance releases. Declared API that is not yet ready to be frozen at time of release can be Provisional API until they are ready for Declared status.

A project can only designate Declared API if this API is used by at least one other project. In some cases it is acceptable for the other project to be a different Linux Tools project.

Deprecation of Declared API can be carried out at the discretion of the project maintainer. However, a viable alternative or explanation why this feature is no longer possible/necessary must be provided as part of the API documentation. Deprecated API can only be removed after a minimum of 2 major releases.

Exceptions can be made, but they must be approved by the PMC and must be accompanied by a message to the community.

Provisional API

<This section is verbatim from WTP_API_Policy at the moment> Provisional API is a work in progress towards fully Declared API and can be used when committers want to gather community feedback before declaring API, or when there are known problems with a new API that cannot be addressed by API freeze date. Provisional API status is meant to be a temporary state and API should not remain provisional for an undue length of time.

Committers should avoid creating Provisional API in any package that would not be appropriate for the final Declared API. This includes package names that use words such as "internal" or "provisional". Labeling existing internal code as provisional is allowed in order to declare a greater degree of support to potential adopters, but committers should exercise care when using this option.

Provisional API should be marked at the class or member level with the following javadoc comment:

   * Provisional API: This class/interface is part of an interim API that is still under development and expected to 
   * change significantly before reaching stability. It is being made available at this early stage to solicit feedback 
   * from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken 
   * (repeatedly) as the API evolves. 

New provisional API must be approved by the component or subproject lead. Due to the risk of stagnation or over-use, leads should ensure that the use is appropriate (e.g. is it ready for feedback? why can't it be declared as API instead?) and that we have a plan for evolution in the subsequent release. A bugzilla must be opened (using "[API]" in the Summary and "provisional" in the Whiteboard) to track the evolution of this code in the following release.

Provisional API may evolve during the first milestones but it must be frozen by the regular API freeze date of a release and will not change for the remainder of the release and the corresponding maintenance releases. Exceptions must be approved by the PMC.

Provisional API should not stagnate. It may be declared as API, undergo extensive change, or be removed at any time in following releases. No approval is necessary, but we strongly recommend that committers notify the community of changes.

Frameworks

API defined in Linux Tools as a framework project falls under the Declared API heading by default immediately their first major release. The project maintainer can selectively mark API as non-Declared before a major release, but once released any API changes must follow the rules laid out above for Declared API.

Currently the only example of a framework project is the Profiling Framework, which contains API for launching and communicating with external tools as well as API for accessing other Eclipse capabilities. It is used by Eclipse Callgraph to create API for launching arbitrary SystemTap scripts.

Internal API

Internal API is API meant for internal use. This can be directly indicated by 'internal' in the package or extension point name, or tagged as 'x-internal' in a manifest file. It can also be assumed that any API not part of a Framework or not otherwise documented as Declared or Provisional falls by default under the Internal category. Internal API may be changed at any time without notice.

Adopters who wish to make use of internal API should post an enhancement request on Bugzilla, and arrangements will be made to expose Internal API as Provisional API in the next major release if appropriate.