Jump to: navigation, search

Eclipse/API Central/API Removal Process

As described in the Eclipse Project Deprecation Policy, there is occasionally a compelling reason to remove old API. This document outlines the process for Eclipse Project committers to remove API from their component. This page is maintained by the Eclipse Project PMC.

  1. 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).
  2. Send an API removal request to the eclipse-pmc mailing list, quoting the bug reference.
  3. 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.
  4. 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).
  5. Annotate all APIs that are to be removed with @noreference, @noextend and @noimplement where applicable, update deprecation comment and add an entry in the porting guide. 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.
  6. Announce the upcoming deletion on all relevant mailing lists, including a link to the bug for community feedback (at least eclipse.org-committers@eclipse.org, cross-project-issues-dev and eclipse-dev). Remind adopters in the announcement to enable API Tools and tell them which API Baseline to use.
  7. 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.
  8. Mark the bug report fixed, with target milestone set to the release in which the deletion occurred.

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.

Process doesn't work for removal of types
bug 482382 explains why this process can't work for an intended removal of types. If you intend to remove API types, you need to come up with a better plan. Re-exported packages suffer from a similar problem.