From 55ab42d75e33a7569bf90bf0652e181f7976ece6 Mon Sep 17 00:00:00 2001 From: Andriy Redko Date: Mon, 14 Aug 2023 13:24:26 -0400 Subject: [PATCH] [Backport] [2.x] [BWC and API enforcement] Define the initial set of annotations, their meaning and relations between them (#9223) (#9296) * [BWC and API enforcement] Define the initial set of annotations, their meaning and relations between them (#9223) * [BWC and API enforcement] Define the initial set of annotations, their meaning and relations between them Signed-off-by: Andriy Redko Signed-off-by: Peter Nied Co-authored-by: Peter Nied (cherry picked from commit 0b2c07a60252292a5a2e41e3af17412ed940886d) * [BWC and API enforcement] Extend the element types the initial set of annotations could be applied to Signed-off-by: Andriy Redko --------- Signed-off-by: Andriy Redko --- CHANGELOG.md | 1 + DEVELOPER_GUIDE.md | 24 +++++++---- .../common/annotation/DeprecatedApi.java | 42 +++++++++++++++++++ .../common/annotation/ExperimentalApi.java | 35 ++++++++++++++++ .../common/annotation/InternalApi.java | 34 +++++++++++++++ .../common/annotation/PublicApi.java | 39 +++++++++++++++++ .../common/annotation/package-info.java | 15 +++++++ 7 files changed, 181 insertions(+), 9 deletions(-) create mode 100644 libs/common/src/main/java/org/opensearch/common/annotation/DeprecatedApi.java create mode 100644 libs/common/src/main/java/org/opensearch/common/annotation/ExperimentalApi.java create mode 100644 libs/common/src/main/java/org/opensearch/common/annotation/InternalApi.java create mode 100644 libs/common/src/main/java/org/opensearch/common/annotation/PublicApi.java create mode 100644 libs/common/src/main/java/org/opensearch/common/annotation/package-info.java diff --git a/CHANGELOG.md b/CHANGELOG.md index da9434edfb3c6..c2a83fa42e536 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), - Prioritize replica shard movement during shard relocation ([#8875](https://github.com/opensearch-project/OpenSearch/pull/8875)) - Introducing Default and Best Compression codecs as their algorithm name ([#9123]()https://github.com/opensearch-project/OpenSearch/pull/9123) - Make SearchTemplateRequest implement IndicesRequest.Replaceable ([#9122]()https://github.com/opensearch-project/OpenSearch/pull/9122) +- [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 `org.apache.logging.log4j:log4j-core` from 2.17.1 to 2.20.0 ([#8307](https://github.com/opensearch-project/OpenSearch/pull/8307)) diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index 09c8321e6edb2..778fe2d4bc5f5 100644 --- a/DEVELOPER_GUIDE.md +++ b/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 diff --git a/libs/common/src/main/java/org/opensearch/common/annotation/DeprecatedApi.java b/libs/common/src/main/java/org/opensearch/common/annotation/DeprecatedApi.java new file mode 100644 index 0000000000000..964380e1a26ce --- /dev/null +++ b/libs/common/src/main/java/org/opensearch/common/annotation/DeprecatedApi.java @@ -0,0 +1,42 @@ +/* + * 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, + ElementType.PARAMETER, + ElementType.FIELD, + ElementType.ANNOTATION_TYPE, + ElementType.MODULE }) +@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 ""; +} diff --git a/libs/common/src/main/java/org/opensearch/common/annotation/ExperimentalApi.java b/libs/common/src/main/java/org/opensearch/common/annotation/ExperimentalApi.java new file mode 100644 index 0000000000000..001ffd6eb720a --- /dev/null +++ b/libs/common/src/main/java/org/opensearch/common/annotation/ExperimentalApi.java @@ -0,0 +1,35 @@ +/* + * 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, + ElementType.PARAMETER, + ElementType.FIELD, + ElementType.ANNOTATION_TYPE, + ElementType.MODULE }) +@PublicApi(since = "2.10.0") +public @interface ExperimentalApi { + +} diff --git a/libs/common/src/main/java/org/opensearch/common/annotation/InternalApi.java b/libs/common/src/main/java/org/opensearch/common/annotation/InternalApi.java new file mode 100644 index 0000000000000..ae58c49e58c5e --- /dev/null +++ b/libs/common/src/main/java/org/opensearch/common/annotation/InternalApi.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; + +/** + * 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, + ElementType.PARAMETER, + ElementType.FIELD, + ElementType.ANNOTATION_TYPE, + ElementType.MODULE }) +@PublicApi(since = "2.10.0") +public @interface InternalApi { + +} diff --git a/libs/common/src/main/java/org/opensearch/common/annotation/PublicApi.java b/libs/common/src/main/java/org/opensearch/common/annotation/PublicApi.java new file mode 100644 index 0000000000000..33862446d6442 --- /dev/null +++ b/libs/common/src/main/java/org/opensearch/common/annotation/PublicApi.java @@ -0,0 +1,39 @@ +/* + * 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, + ElementType.PARAMETER, + ElementType.FIELD, + ElementType.ANNOTATION_TYPE, + ElementType.MODULE }) +@PublicApi(since = "2.10.0") +public @interface PublicApi { + /** + * Version when this API was released + */ + String since(); +} diff --git a/libs/common/src/main/java/org/opensearch/common/annotation/package-info.java b/libs/common/src/main/java/org/opensearch/common/annotation/package-info.java new file mode 100644 index 0000000000000..7bb79d7579747 --- /dev/null +++ b/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;