Jump to: navigation, search

Difference between revisions of "Provisional API Guidelines Update Proposal"

m (Overview)
Line 2: Line 2:
  
 
== Overview ==
 
== Overview ==
[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.  
+
[http://www.eclipse.org/projects/dev_process/eclipse-quality.php Eclipse quality] APIs do not appear fully formed out of nowhere.  All APIs undergo a development process, passing through many phases from initial embryonic 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.  
  
 
The development cycle for each major and minor 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. Prior to the API freeze, all new code is subject to change at any time. After the API freeze, code designated as API and provisional API will remain binary backward compatible except by prior notification and approval of the relevant PMC and sufficient notice to the community.  After API is released, all future releases will remain binary compatible as specified [[somewhere else]].  
 
The development cycle for each major and minor 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. Prior to the API freeze, all new code is subject to change at any time. After the API freeze, code designated as API and provisional API will remain binary backward compatible except by prior notification and approval of the relevant PMC and sufficient notice to the community.  After API is released, all future releases will remain binary compatible as specified [[somewhere else]].  

Revision as of 00:19, 3 February 2009

The following is a work in progress proposal to update the Provisional API Guidelines.

Overview

Eclipse quality APIs do not appear fully formed out of nowhere. All APIs undergo a development process, passing through many phases from initial embryonic 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.

The development cycle for each major and minor 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. Prior to the API freeze, all new code is subject to change at any time. After the API freeze, code designated as API and provisional API will remain binary backward compatible except by prior notification and approval of the relevant PMC and sufficient notice to the community. After API is released, all future releases will remain binary compatible as specified somewhere else.

For the purposes of the binary compatibility contract, "provisional API" is classified as internal or non-API code. There are no guarantees about the existence or shape of internal code, even if the package name or comments suggest that it may become API in the next release. In particular, the API contract (binary backwards compatibility) does not apply. Clients who think they must use internal code may do so at their own risk, or with slightly less risk if they can reach an agreement with the team that developed the internal code. Note also that in such cases, the required versions for plug-in dependencies need to be specified with great care.

Definition of terms used in this document

API package 
Any package that is not marked with x-internal:=true in the hosting bundle manifest.
Internal package 
Any Java package marked with x-internal:=true in hosting bundle manifest.
Provisional API 
A visible member or type of a bundle that is made available for early access to consumers but is not subject to the binary backwards compatibility contract of full API.

Guidelines for producers of provisional API

Package naming

Provisional API code may be in a package whose name contains the segment "internal" or "internal.provisional". Neither is required.

Bundle manifest

All API packages should be exported unconditionally by the bundle manifest. All provisional API packages must be exported using the x-internal:=true directive.

Package versions

Provisional API packages must be exported with version and use the same package versioning rules as API packages. The package version must evolve independently from the Bundle-Version of the exporter. For example, the first release a provisional API some.cool.stuff might appear as follows:

   Bundle-Version: 3.0.0
   Export-Package: some.cool.stuff; version=1.0; x-internal:=true

Bundle version numbers

As defined in the Version Numbering guidelines, the version number of a bundle is tied to the evolution of the API in the bundle. Internal code generally influences only the service segment of the bundle version. Provisional API is not formal API and so should be treated as internal code for the purposes of updating bundle version numbers. That is, increasing the version of a provisional package should result in at least the service segment of the exporting bundle's version being incremented.

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 3.4 release of Eclipse, a tag of @since 3.4 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:

* PROVISIONAL This [type|member] has been added as part of a work in progress. 
* It is not guaranteed to work or remain the same in future releases. 
* @provisional This [type|member] has been added as part of a work in progress. 
* It is not guaranteed to work or remain the same in future releases. 

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.

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 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 integration builds are not broken due to changes in provisional APIs. Known clients of the provisional API in the community 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 provisional 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 I20380119. Method {@link #blort()} should be used instead.

Note that while there are no restrictions on changing internal (aka non-API) code before or after the API freeze, it is recommended that provisional API not be changed after the API freeze as the expectation is that there will be external consumers.

Graduating provisional API

When a provisional API graduates, the x-internal flag is removed and the version number evolves as per the API package guidelines.

Guidelines for producers of provisional API

Early Adopter Consumption

Early adopters should use Import-Package to declare a dependency on provisional API. Proper version ranges should be used to ensure a compatible version of the provisional API is used.

   Import-Package: some.cool.stuff; version="[1.0, 2.0)"