Difference between revisions of "Provisional API Guidelines"

Revision as of 12:56, 23 February 2006

Eclipse quality APIs don't appear fully formed out of nowhere. All APIs undergo a development process, passing through many phases from initial embroyonic forms to real battle-hardened APIs with guarantees of long term support. It is important that API clients understand the state of the APIs in any given build of Eclipse. This document sets out guidelines for Eclipse Project committers on how to indicate APIs that are still under development and subject to change. These guidelines are also useful for API clients who want to know about the state of a given API they are using.

The development cycle for each major and minor Eclipse project release has a milestone designated as the API freeze. The rules for development and treatment of APIs are different for the periods before and after this point, so this document outlines guidelines for both phases of the development cycle.

Definition of terms used in this document:

API package 

Any package that does not contain the segment "internal". (see Naming Conventions for details)

non-API package 

Any Java package containing the segment "internal".

API element 

A public Java class or interface in an API package, or a public or protected method or field in such a class or interface

Provisional API 

An API element that has not existed in any release of the Eclipse project. All provisional API is subject to arbitrary change or removal without any notice. Although the Eclipse quality guidelines distinguish between several forms of transient APIs, this document will refer to all non-final APIs simply as provisional APIs.

<div id="pre_freeze"/>

Provisional APIs prior to the API freeze

Prior to the API freeze, any API element that did not exist in the previous release is provisional by definition. This is true regardless of the package name, bundle manifest, or javadoc of the types involved. However, the conventions below should be used to indicate where API is provisional.

Package naming

Provisional API can appear in any package. Typically if the provisional API is intended to become real API in time for the release, it will appear in an API package. Provisional APIs that are not intended to become real API in time for the release should be in a non-API package. If provisional API is in a non-API package, it should kept in a separate package from code that is never intended to become API. The "internal.provisional" naming convention can be used, but is not required, to separate provisional API from true internal code within the internal package namespace.

Bundle manifest

All API packages should be exported unconditionally by the bundle manifest. All non-API packages should be exported and marked x-internal.

Javadoc

The primary indicator of provisional API is the @since tag, indicating that it was introduced during the current development period. For example, during development leading up to the 4.0 release of Eclipse, a tag of @since 4.0 designates provisional API. If the API is particularly volatile, experimental, or at risk of removal, a further comment in the javadoc can be used to clarify the state of the API:

* <p>
* EXPERIMENTAL. This class or interface has been added as
* part of a work in progress. There is no guarantee that this API will
* work or that it will remain the same. Please do not use this API without
* consulting with the <Your Team Name> team.
* </p>

Though not required, inserting this paragraph in your class or interface javadoc makes the state of the API very clear to potential clients. By indicating the name of the responsible team in the comment, you allow for interaction with prospective clients. If a prospective API client contacts the developer of the provisional API, they can agree on a certain level of stability and advanced warning before changes are made in the API. Also note that while you don't need to use the exact template described above, a consistent template does make it easier to find and remove these comments when finalizing the API.

Provisional APIs after the API freeze

After the API freeze, all code in API packages is no longer considered provisional

Changing provisional APIS

Technically, a provisional API can change arbitrarily or be removed at any time without notice. Clients in the greater community who are consuming Eclipse milestone and integration builds cannot make any assumptions about the state of any provisional API between any two non-release builds. However, committers have a shared responsibility to ensure Eclipse Project integration builds are not broken due to changes in provisional APIs. Known clients of the provisional API within the SDK should be given fair warning and a chance to react before breaking changes are made. As a courtesy to the community, and to minimize the risk of build failures, it is useful to deprecate APIs slated for change or removal in at least one integration build before making the change. Although not required, adding such a temporary tag can ease the transition for early adopters of the API:

* @deprecated This API will be removed in I20090422. Method {@link #blort()} should be used instead.