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.  These guidelines set out how to indicate APIs that are still under development and subject to change.  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 such APIs as simply 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 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.
  
 
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 12: Line 12:
 
== Provisional APIs prior to the API freeze ==
 
== Provisional APIs prior to the API freeze ==
  
Prior to the API freeze, any class, interface, method or field in an API package.
+
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:
 +
<code>
 +
* <p>
 +
* <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
 +
* work or that it will remain the same. Please do not use this API without
 +
* consulting with the &lt;Your Team Name&gt; team.
 +
* </p>
 +
</code>
 +
 
 +
dfd

Revision as of 11:09, 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 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 Eclipse quality guidelines distinguish between several forms of transient APIs, this document will refer to all non-final APIs simply as provisional APIs.

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 Java class, interface, method, or field in an API package

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

*

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

dfd