Difference between revisions of "Provisional API Guidelines"

From Eclipsepedia

Jump to: navigation, search
Line 1: Line 1:
[http://www.eclipse.org/projects/dev_process/eclipse-quality.php 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 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. Although the [http://www.eclipse.org/projects/dev_process/eclipse-quality.php Eclipse quality] guidelines distinguish between several forms of transient APIs, this document will refer to all non-final APIs simply as provisional APIs.
+
[http://www.eclipse.org/projects/dev_process/eclipse-quality.php 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.
 
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.
Line 7: Line 7:
 
; API package : Any package that does not contain the segment "internal". (see [[Naming Conventions]] for details)
 
; 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".
 
; non-API package : Any Java package containing the segment "internal".
; API element : A Java class, interface, method, or field in an API package
+
; 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 [http://www.eclipse.org/projects/dev_process/eclipse-quality.php 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"/>
 
<div id="pre_freeze"/>
 
== Provisional APIs prior to the API 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 automatically designated as provisional. This is primarily indicated through use of 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:
+
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.
 +
 
 +
<h3>Package naming</h3>
 +
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.
 +
 
 +
<h3>Bundle manifest</h3>
 +
All API packages should be exported unconditionally by the bundle manifest.  All non-API packages should be exported and marked x-internal.
 +
 
 +
<h3>Javadoc</h3>
 +
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:
 
<code>
 
<code>
  * <p>
+
  * &lt;p&gt;
 
  * <strong>EXPERIMENTAL</strong>. This class or interface has been added as
 
  * <strong>EXPERIMENTAL</strong>. This class or interface has been added as
 
  * part of a work in progress. There is no guarantee that this API will
 
  * 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
 
  * work or that it will remain the same. Please do not use this API without
 
  * consulting with the &lt;Your Team Name&gt; team.
 
  * consulting with the &lt;Your Team Name&gt; team.
  * </p>
+
  * &lt;/p&gt;
 
</code>
 
</code>
  
dfd
+
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:
 +
<code>
 +
* @deprecated This API will be removed in I20090422. Method {@link #blort()} should be used instead.
 +
</code>

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"/>

Contents

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.