Eclipse/API Central/API Removal Process

From Eclipsepedia

Jump to: navigation, search

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. Announce the upcoming deletion on relevant mailing lists, including a link to the bug for community comment (at least cross-project-issues-dev and eclipse-dev).
  6. Assuming no community disagreement, update deprecation comment and add an entry in porting guide. The deprecation comment and porting guide entry must also include a link to the bug report to allow for further feedback from API adopters.
  7. After the required waiting period has gone by, the API is removed and the porting guide entry is moved from the "upcoming deletions" to the "deleted API" 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.