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.
Difference between revisions of "Eclipse/API Central/Deprecation Policy"
(→Retention of Deprecated API) |
|||
| Line 1: | Line 1: | ||
| − | This page contains | + | This page contains '''DRAFT''' [[Eclipse Project]] guidelines on API deprecation. |
= What is Deprecation? = | = What is Deprecation? = | ||
Revision as of 11:22, 23 October 2009
This page contains DRAFT Eclipse Project guidelines on API deprecation.
Contents
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. 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, deleted 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 [1]
Java API
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
Extension Points
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.
Retention 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. Where possible, deprecated API that is slated for future removal will have a comment to that effect in the deprecation comment.
The Eclipse Project policy is to maintain deprecated API:
- In all future service releases after the release in which the deprecation occurred. For example if an API is deprecated in the 3.x release, it will be continue to exist in 3.x.1, 3.x.2, 3.x.3, etc, for as long as service releases of that minor release continue.
- In at least two subsequent minor (annual) releases after the release in which the deprecation occurred. For example if an API is deprecated in release 2.0, it will continue to exist in 2.1 and 2.2, but may be deleted in 2.3 and beyond.
- API may be deleted in a subsequent major release, regardless of the elapsed time between the deprecation and the arrival of the next major release. For example if an API is deprecated in release 3.9, one month later release 4.0 can occur in which the deprecated API is removed.
In addition, the Eclipse Project will not delete deprecated API as part of an Eclipse Foundation simultaneous release if any other projects in that release are using the deprecated API and are unable to cease using it.