From bda95b39b55b3801c246a4affacab7f16ab4e67b Mon Sep 17 00:00:00 2001
From: Lars Vogel <Lars.Vogel@vogella.com>
Date: Thu, 21 Dec 2023 16:42:18 +0100
Subject: [PATCH] API removal process migrated from the
 https://github.com/eclipse-platform/.github/wiki/PMC-project-guidelines

https://wiki.eclipse.org/Eclipse/API_Central/API_Removal_Process was originally migrated to https://github.com/eclipse-platform/.github/wiki/PMC-project-guidelines, I think it is better stored in the repo as mark-down document
---
 docs/ApiRemovalProcess.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)
 create mode 100644 docs/ApiRemovalProcess.md

diff --git a/docs/ApiRemovalProcess.md b/docs/ApiRemovalProcess.md
new file mode 100644
index 00000000000..85b921d9b7a
--- /dev/null
+++ b/docs/ApiRemovalProcess.md
@@ -0,0 +1,27 @@
+# API removal process
+
+See [Eclipse Project Deprecation Policy](https://wiki.eclipse.org/Eclipse/API_Central/Deprecation_Policy) for more information.
+
+For new API planned removals use:
+
+* For Java code use the @Deprecated annotation (see below for an example) and optional additional Javadoc. This can only be applied for bundles using a minimum BREE of Java 11. An extra entry in the removal document from [removal document](https://github.com/eclipse-platform/eclipse.platform.common/blob/master/bundles/org.eclipse.platform.doc.isv/porting/removals.html) is not necessary anymore
+* Keep the [removal document](https://github.com/eclipse-platform/eclipse.platform.common/blob/master/bundles/org.eclipse.platform.doc.isv/porting/removals.html) for cases in which the bundle is below Java 11 or for other special which do not fit into the Java code. For such cases a new entry is necessary for planned API removals
+* If appropriate the @noextend @noreference and @noinstantiate Javadoc annotation should be added to code
+
+PMC approval for planned API removal is required, either via the pull request or via the mailing list
+After 2 years of announced deletion, the API can be removed
+Javadoc generates a detailed [list of forRemoval](http://help.eclipse.org/latest/topic/org.eclipse.platform.doc.isv/reference/api/deprecated-list.html#forRemoval) API which is also link to in the [removal document](https://github.com/eclipse-platform/eclipse.platform.common/blob/master/bundles/org.eclipse.platform.doc.isv/porting/removals.html)
+
+Example of a deprecation comment:
+
+``` 
+* XXX
+ * @noreference
+ * @noextend
+ * @noimplement
+ * @deprecated This XXX (class/method/field) will be removed in a future release. Use XXX instead.
+ */
+@Deprecated(forRemoval = true, since = "4.16")
+``` 
+* The PMC may decide to back out of an API removal
+* In general, removing a deprecated API does NOT cause the increase of the major version segment.