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/API Removal Process"

m
(20 intermediate revisions by 6 users not shown)
Line 1: Line 1:
As described in the [[Eclipse/API_Central/Deprecation_Policy|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/PMC|Eclipse Project PMC]].
+
See [[Eclipse/API_Central/Deprecation_Policy|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/PMC|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 <code>@noreference</code>, <code>@noextend</code> and <code>@noimplement</code> where applicable, update deprecation comment and add an entry in the [https://git.eclipse.org/c/platform/eclipse.platform.common.git/tree/bundles/org.eclipse.platform.doc.isv/porting/removals.html 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.
 +
# 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.
 +
# 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.
 +
 
 +
[[Category:API]]
 +
[[Category:Eclipse Project]]

Revision as of 11:17, 23 March 2018

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.

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

Back to the top