[BWC and API enforcement] Define the initial set of annotations, thei…

…r meaning and relations between them (opensearch-project#9223)

* [BWC and API enforcement] Define the initial set of annotations, their meaning and relations between them

Signed-off-by: Andriy Redko <[email protected]>
Signed-off-by: Peter Nied <[email protected]>
Co-authored-by: Peter Nied <[email protected]>

CHANGELOG.md

@@ -11,6 +11,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - Add events correlation engine plugin ([#6854](https://github.com/opensearch-project/OpenSearch/issues/6854))
 - Introduce new dynamic cluster setting to control slice computation for concurrent segment search ([#9107](https://github.com/opensearch-project/OpenSearch/pull/9107))
 - Implement on behalf of token passing for extensions ([#8679](https://github.com/opensearch-project/OpenSearch/pull/8679))
+- [BWC and API enforcement] Define the initial set of annotations, their meaning and relations between them ([#9223](https://github.com/opensearch-project/OpenSearch/pull/9223))
 
 ### Dependencies
 - Bump `log4j-core` from 2.18.0 to 2.19.0

DEVELOPER_GUIDE.md

@@ -569,13 +569,19 @@ use Version checks accordingly (e.g., `Version.onOrAfter`, `Version.before`) to
 
 #### Developer API
 
-The Developer API consists of interfaces and foundation software implementations that enable external users to develop new OpenSearch features. This includes
-obvious components such as the Plugin framework and less obvious components such as REST Action Handlers. When developing a new feature of OpenSearch it is important
-to explicitly mark which implementation components may, or may not, be extended by external implementations. For example, all new API classes with `@opensearch.api`
-signal that the new component may be extended by an external implementation and therefore provide backwards compatibility guarantees. Similarly, any class explicitly
-marked with the `@opensearch.internal` annotation, or not explicitly marked by an annotation should not be extended by external implementation components as it does not
-guarantee backwards compatibility and may change at any time. The `@deprecated` annotation should also be added to any `@opensearch.api` classes or methods that are
-either changed or planned to be removed across minor versions.
+The Developer API consists of interfaces and foundation software implementations that enable external users to develop new OpenSearch features. This includes obvious
+components such as the Plugin and Extension frameworks and less obvious components such as REST Action Handlers. When developing a new feature of OpenSearch it is
+important to explicitly mark which implementation components may, or may not, be extended by external implementations. For example, all new API classes with
+`@PublicApi` annotation (or documented as `@opensearch.api`) signal that the new component may be extended by an external implementation and therefore provide
+backwards compatibility guarantees. Similarly, any class explicitly marked with the `@InternalApi` (or documented as `@opensearch.internal`) annotation, or not
+explicitly marked by an annotation should not be extended by external implementation components as it does not guarantee backwards compatibility and may change at
+any time. The `@DeprecatedApi` annotation could also be added to any classes annotated with `@PublicApi` (or documented as `@opensearch.api`) or their methods that
+are either changed (with replacement) or planned to be removed across major versions.
+
+The APIs which are designated to be public but have not been stabilized yet should be marked with `@ExperimentalApi` (or documented as `@opensearch.experimental`) 
+annotation. The presence of this annotation signals that API may change at any time (major, minor or even patch releases). In general, the classes annotated with
+`@PublicApi` may expose other classes or methods annotated with `@ExperimentalApi`, in such cases the backward compatibility guarantees would not apply to latter
+(see please [Experimental Development](#experimental-development) for more details).
 
 #### User API
 
@@ -592,8 +598,8 @@ and a log message to the OpenSearch deprecation log files using the `Deprecation
 Rapidly developing new features often benefit from several release cycles before committing to an official and long term supported (LTS) API. To enable this cycle OpenSearch
 uses an Experimental Development process leveraging [Feature Flags](https://featureflags.io/feature-flags/). This allows a feature to be developed using the same process as
 a LTS feature but with additional guard rails and communication mechanisms to signal to the users and development community the feature is not yet stable, may change in a future
-release, or be removed altogether. Any Developer or User APIs implemented along with the experimental feature should be marked with the `@opensearch.experimental` annotation to
-signal the implementation is not subject to LTS and does not follow backwards compatibility guidelines.
+release, or be removed altogether. Any Developer or User APIs implemented along with the experimental feature should be marked with `@ExperimentalApi` (or documented as
+`@opensearch.experimental`) annotation to signal the implementation is not subject to LTS and does not follow backwards compatibility guidelines.
 
 ### Backports
 

libs/common/src/main/java/org/opensearch/common/annotation/DeprecatedApi.java

@@ -0,0 +1,34 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ */
+
+package org.opensearch.common.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Target;
+
+/**
+ * Marks the public APIs as deprecated and scheduled for removal in one of the upcoming
+ * major releases. The types marked with this annotations could only be other {@link PublicApi}s.
+ *
+ * @opensearch.api
+ */
+@Documented
+@Target({ ElementType.TYPE, ElementType.PACKAGE, ElementType.METHOD, ElementType.CONSTRUCTOR })
+@PublicApi(since = "2.10.0")
+public @interface DeprecatedApi {
+    /**
+     * Version since this API is deprecated
+     */
+    String since();
+
+    /**
+     * Next major version when this API is scheduled for removal
+     */
+    String forRemoval() default "";
+}

libs/common/src/main/java/org/opensearch/common/annotation/ExperimentalApi.java

@@ -0,0 +1,27 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ */
+
+package org.opensearch.common.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Target;
+
+/**
+ * Experimental APIs that may not retain source and binary compatibility within major,
+ * minor or patch releases. The types marked with this annotations could only expose
+ * other {@link PublicApi} or {@link ExperimentalApi} types as public members.
+ *
+ * @opensearch.api
+ */
+@Documented
+@Target({ ElementType.TYPE, ElementType.PACKAGE, ElementType.METHOD, ElementType.CONSTRUCTOR })
+@PublicApi(since = "2.10.0")
+public @interface ExperimentalApi {
+
+}

libs/common/src/main/java/org/opensearch/common/annotation/InternalApi.java

@@ -0,0 +1,26 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ */
+
+package org.opensearch.common.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Target;
+
+/**
+ * Internal APIs that have no compatibility guarantees and should be not used outside
+ * of OpenSearch core components.
+ *
+ * @opensearch.api
+ */
+@Documented
+@Target({ ElementType.TYPE, ElementType.PACKAGE, ElementType.METHOD, ElementType.CONSTRUCTOR })
+@PublicApi(since = "2.10.0")
+public @interface InternalApi {
+
+}

libs/common/src/main/java/org/opensearch/common/annotation/PublicApi.java

@@ -0,0 +1,31 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ */
+
+package org.opensearch.common.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Target;
+
+/**
+ * Stable public APIs that retain source and binary compatibility within a major release.
+ * These interfaces can change from one major release to another major release
+ * (e.g. from 1.0 to 2.0). The types marked with this annotations could only expose
+ * other {@link PublicApi} or {@link ExperimentalApi} types as public members.
+ *
+ * @opensearch.api
+ */
+@Documented
+@Target({ ElementType.TYPE, ElementType.PACKAGE, ElementType.METHOD, ElementType.CONSTRUCTOR })
+@PublicApi(since = "2.10.0")
+public @interface PublicApi {
+    /**
+     * Version when this API was released
+     */
+    String since();
+}

libs/common/src/main/java/org/opensearch/common/annotation/package-info.java

@@ -0,0 +1,15 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ */
+
+/**
+ * The OpenSearch API related annotations
+ *
+ * @opensearch.api
+ */
+@PublicApi(since = "2.10.0")
+package org.opensearch.common.annotation;