Eclipse/API Central/Deprecation Policy
This page contains DRAFT Eclipse Project guidelines on API deprecation.
What is Deprecation?
Despite our best efforts, we don't always craft API that remains perfect forever. Often new and better approaches come along that supersede old ways of doing things. API deprecation is used to inform API clients that a particular API element is no longer recommended for use. The deprecation comment should describe the reason for the deprecation, and directions for how to replace their usage with the new recommended way of doing things. Valid reasons for deprecating API may include:
- The old API contract requires the implementation to be buggy, inefficient, or unable to handle all possible use cases
- The old API has been, or will be, no longer available in a later release
- The old API is redundant, duplicating functionality available elsewhere
Identifying Deprecated API
This section describes how clients can identify what API is deprecated. To identify API from non-API, see 
Java API is deprecated through use of the @deprecated javadoc tag on types, methods, and fields. The javadoc paragraph following the @deprecated tag defines the rationale for the deprecation and instructions on moving to equivalent new API
Elements and attributes in extension points are deprecated by setting the "Deprecated" property to true in the PDE extension point schema editor. The entire extension point can be deprecated by deprecating the "extension" element, which is the top level element at the root of any contribution to the extension point.
Removal of Deprecated API
Often there is no sufficiently compelling reason to ever remove deprecated API, so the API may remain in place indefinitely after the release in which it was deprecated. However, there are situations where continuing to maintain the deprecated API creates too high a burden for both API developers and clients: the code bloat of keeping old implementations, the added complexity of multiple redundant APIs, etc.
The Eclipse Project policy is to maintain deprecated API:
- In all Eclipse project releases for two years after the release in which the intent to remove the deprecated API is announced. For example if an API is deprecated in release 2.0, and the intent to remove the API is announced in release 2.1, it will continue to exist in 2.2 and 2.3, but may be deleted in 2.4 and beyond. The intent to remove deprecated API can be announced at the same time the deprecation is made.
- Deprecated API will never be removed in service releases
Announcing API Removal
API removal must be widely announced to adopters to give them sufficient time to react to the impending change. API removals will be announced via the following channels:
- In the deprecation comment of the API to be removed
- In the porting guide of each release up to and including the release in which the API is removed
- On all relevant mailing lists for the component, in addition to cross-project-issues-dev.
Objections raised to the announced removal will be considered, and options such as delaying removal, abandoning removal, or supplying compatibility support for affected clients will be considered based on community feedback.
Bundle and Package Versions
As described in the Version Numbering guidelines, removal of any API is a breaking change, so the major version of bundles and packages exporting the API must increment their major version number and reset the minor and service numbers to zero.