Eclipse/API Central/API Removal Process
See Eclipse Project Deprecation Policy for the API deprecation process. This document outlines the process for Eclipse Project committers to remove API from their component. This page is maintained by the Eclipse Project PMC.
- Enter a bug report describing the proposed removal. Include precise details about what packages, classes, methods, or fields are to be removed, the reason why removal is needed, and the anticipated impact on downstream clients (estimate on how widely the API is being used).
- Send an API removal request to the eclipse-pmc mailing list, quoting the bug reference.
- The PMC will discuss and come to agreement on a PMC weekly call, and mark pmc_approved+ on the bug if approved. Because deletion has potentially high impact, deletion requires consensus from all active PMC members, rather than a single PMC member vote on the bug.
- Only if there is a lot of (potentially confusing) discussion on the original "request deletion" bug: clone the bug in order to create a fresh community feedback channel (bugzilla clone will keep a reference to the original bug in the description).
- Annotate all APIs that are to be removed with
@noimplementwhere applicable, update deprecation comment and add an entry in the porting guide. Do the same for API that depends on it. The deprecation comment and porting guide entry must explain how to adapt the client code and also include a link to the bug report to allow feedback from API adopters.
- Usage of
@Deprecated(forRemoval=true)Java annotation is strongly recommended where possible to strengthen the message to adopters.
- Announce the upcoming deletion on the cross-project-issues-dev mailing list including a link to the bug for community feedback. Remind adopters in the announcement to enable API Tools and tell them which API Baseline to use.
- If there is no substantial community disagreement (the PMC may decide to cancel the change if the impact of removal outweighs the benefits) and after the two year waiting period has gone by, the API is removed and the porting guide entry is moved from the "Planned API removals" to the "Removed APIs" section in the documentation. In general, removing a deprecated API does NOT cause the increase of the major version segment.
- Mark the bug report fixed, with target milestone set to the release in which the deletion occurred.
Backing out of removal
Note that although PMC approval occurs early in the process, either the PMC or the component lead may decide to back out of the proposed removal at any point during the two year waiting period between announcement and deletion. This can occur for example if community feedback indicates that the removal will have high impact for clients, or other changes in the API require the API to be kept. In this case, the API removal bug should be marked as WONTFIX, and the deletion notice removed from the porting guide and deprecation comment.
Example of a deprecation comment:
/** * XXX * @noreference * @noextend * @noimplement * @deprecated This XXX (class/method/field) will be removed in a future release. See * https://bugs.eclipse.org/bugs/show_bug.cgi?id=XXX for more * information. Use XXX instead. */ @Deprecated(forRemoval=true)