Skip to main content
Jump to: navigation, search

Provisional API Guidelines Update Proposal

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


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.
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.
Internal package 
Any Java package marked with x-internal:=true in hosting bundle manifest.

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 might appear as follows:

   Bundle-Version: 3.0.0
   Export-Package:; 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.


The primary indicator of provisional API is the @provisional tag. This indicates the API is particularly volatile, experimental, or at risk of removal. The comment following the Javadoc tag must clarify the state of the API as follows:

* @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. 
* For more information contact <your project mailing list>

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 strongly recommended that provisional API not be changed after the API freeze as the expectation is that there will actually be external consumers. Similarly, changing provisional API in a maintenance release is strongly discouraged as it will break the desired early adopters.

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:; version="[1.0, 2.0)"

Back to the top