Skip to main content

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.

Jump to: navigation, search

Difference between revisions of "Eclipse/API Central/Deprecation Policy"

(References)
(Removal of Deprecated API)
(26 intermediate revisions by 3 users not shown)
Line 1: Line 1:
This page contains draft [[Eclipse Project]] guidelines on API deprecation.
+
This page contains [[Eclipse Project]] guidelines on API deprecation. This page is maintained by the [[Eclipse/PMC]].
  
 
= What is 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. 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.
+
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 will no longer be available in a later release
 +
* The old API is redundant, duplicating functionality available elsewhere
 +
 
 +
Note that deprecated APIs still have to work as originally specified. If an API is widely used and not clearly broken, then we shouldn't add migration work for clients. Sometimes, the best solution is to add a "Note: " paragraph instead of deprecating an API.
 +
 
 +
== Process to deprecate an API ==
 +
* Open a bug with your arguments
 +
* Get a review from
 +
** the component lead
 +
** the author or current maintainer of the API (use Show Annotations / History)
 +
 
 +
If you intend to remove the API, make sure your proposal fits [[#Removal_of_Deprecated_API]].
  
 
= Identifying Deprecated API =
 
= Identifying Deprecated API =
 +
 +
This section describes how clients can identify what API is deprecated. To identify API from non-API, see [http://www.eclipse.org/articles/Article-API%20use/eclipse-api-usage-rules.html]
  
 
== Java API ==
 
== 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 ==
 
== Extension Points ==
  
= Retention of Deprecated 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.
 +
 
 +
[[image:Schema-deprecation.png‎]]
 +
 
 +
= Removal of Deprecated API =
 +
 
 +
Deprecated API can be marked for deletion.
 +
This applies to situations where continuing to maintain the deprecated
 +
API creates a burden for API developers or clients or if the code
 +
bloat of keeping old implementations or adds complexity because of
 +
multiple redundant APIs, etc.
 +
 
 +
== Retention Policy ==
 +
 
 +
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 [[#Announcing API Removal|announced]]. For example if an API is deprecated in a release in June 2006, and the intent to remove the API is [[#Announcing API Removal|announced]] in a release in June 2007, it will continue to exist in all release until the end of June 2009 (inclusive). Following the usual Eclipse Project release schedule this means the deprecated API will continue to exist in the next two minor releases after the release in which the removal is announced. The intent to remove deprecated API can be announced in the same release that the deprecation is made.
 +
* In all service (maintenance) releases. Deprecated API will never be removed in a service release.
 +
 
 +
== 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. For complete details see the [[Eclipse/API_Central/API_Removal_Process|API Removal Process]].
 +
 
 +
== Approval ==
 +
 
 +
Removal of any [[Eclipse Project]] API requires approval from the [[Eclipse/PMC|Eclipse Project PMC]].
 +
 
 +
== Third Party API ==
 +
 
 +
The Eclipse Project consumes and delivers bundles that are produced by other projects (including Orbit, ECF, and Equinox). The Eclipse Project sometimes consumes new major versions of these bundles, which may include API removals or other breaking changes in those bundles. As long as those changes don't affect the API of Eclipse Project bundles, such changes to third party bundles can happen at any time and without a two year waiting period. If those changes affect the API of Eclipse Project bundles, for example they are re-exported by Eclipse Project bundles or extended by Eclipse Project API, then this deprecation policy will be in effect. That is, the intent to remove API will be announced and will the API will remain in place for two full years prior to a release containing the deletion.
 +
 
 +
== Bundle and Package Versions ==
 +
The PMC will decide case-by-case whether to increase the major or minor version.
  
 
= References =
 
= References =
Line 17: Line 71:
 
* [http://java.sun.com/j2se/1.4.2/docs/guide/misc/deprecation/deprecation.html Java Deprecation Guidelines]
 
* [http://java.sun.com/j2se/1.4.2/docs/guide/misc/deprecation/deprecation.html Java Deprecation Guidelines]
 
* [[Architecture Council/Meetings/API Deprecation 20080119]]
 
* [[Architecture Council/Meetings/API Deprecation 20080119]]
 +
 +
[[Category:API]]
 +
[[Category:Eclipse Project]]

Revision as of 12:13, 17 November 2017

This page contains Eclipse Project guidelines on API deprecation. This page is maintained by the Eclipse/PMC.

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 will no longer be available in a later release
  • The old API is redundant, duplicating functionality available elsewhere

Note that deprecated APIs still have to work as originally specified. If an API is widely used and not clearly broken, then we shouldn't add migration work for clients. Sometimes, the best solution is to add a "Note: " paragraph instead of deprecating an API.

Process to deprecate an API

  • Open a bug with your arguments
  • Get a review from
    • the component lead
    • the author or current maintainer of the API (use Show Annotations / History)

If you intend to remove the API, make sure your proposal fits #Removal_of_Deprecated_API.

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.

Schema-deprecation.png

Removal of Deprecated API

Deprecated API can be marked for deletion. This applies to situations where continuing to maintain the deprecated API creates a burden for API developers or clients or if the code bloat of keeping old implementations or adds complexity because of multiple redundant APIs, etc.

Retention Policy

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 a release in June 2006, and the intent to remove the API is announced in a release in June 2007, it will continue to exist in all release until the end of June 2009 (inclusive). Following the usual Eclipse Project release schedule this means the deprecated API will continue to exist in the next two minor releases after the release in which the removal is announced. The intent to remove deprecated API can be announced in the same release that the deprecation is made.
  • In all service (maintenance) releases. Deprecated API will never be removed in a service release.

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:

  1. In the deprecation comment of the API to be removed
  2. In the porting guide of each release up to and including the release in which the API is removed
  3. 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. For complete details see the API Removal Process.

Approval

Removal of any Eclipse Project API requires approval from the Eclipse Project PMC.

Third Party API

The Eclipse Project consumes and delivers bundles that are produced by other projects (including Orbit, ECF, and Equinox). The Eclipse Project sometimes consumes new major versions of these bundles, which may include API removals or other breaking changes in those bundles. As long as those changes don't affect the API of Eclipse Project bundles, such changes to third party bundles can happen at any time and without a two year waiting period. If those changes affect the API of Eclipse Project bundles, for example they are re-exported by Eclipse Project bundles or extended by Eclipse Project API, then this deprecation policy will be in effect. That is, the intent to remove API will be announced and will the API will remain in place for two full years prior to a release containing the deletion.

Bundle and Package Versions

The PMC will decide case-by-case whether to increase the major or minor version.

References

Back to the top