Jump to: navigation, search

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. 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

References