Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Provisional API Guidelines
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