From 279ae2d739ed22dda87131ab64ffacb04bdfb59b Mon Sep 17 00:00:00 2001 From: Andriy Redko Date: Thu, 10 Aug 2023 09:52:06 -0400 Subject: [PATCH 1/4] [BWC and API enforcement] Define the initial set of annotations, their meaning and relations between them Signed-off-by: Andriy Redko --- CHANGELOG.md | 1 + DEVELOPER_GUIDE.md | 24 +++++++++----- .../common/annotation/DeprecatedApi.java | 33 +++++++++++++++++++ .../common/annotation/ExperimentalApi.java | 26 +++++++++++++++ .../common/annotation/InternalApi.java | 25 ++++++++++++++ .../common/annotation/PublicApi.java | 27 +++++++++++++++ .../common/annotation/package-info.java | 14 ++++++++ 7 files changed, 141 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 3799b8a2db9bf..d0d0c45096503 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), - Allow mmap to use new JDK-19 preview APIs in Apache Lucene 9.4+ ([#5151](https://github.com/opensearch-project/OpenSearch/pull/5151)) - 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)) +- [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 diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index 1dce1f8a75035..f9936aad0cf8c 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..3a4c1e527a79c --- /dev/null +++ b/libs/common/src/main/java/org/opensearch/common/annotation/DeprecatedApi.java @@ -0,0 +1,33 @@ +/* + * 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 }) +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..dfa9c2dc8c4ae --- /dev/null +++ b/libs/common/src/main/java/org/opensearch/common/annotation/ExperimentalApi.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; + +/** + * 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 }) +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..39c0a42464671 --- /dev/null +++ b/libs/common/src/main/java/org/opensearch/common/annotation/InternalApi.java @@ -0,0 +1,25 @@ +/* + * 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 }) +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..0b13899681854 --- /dev/null +++ b/libs/common/src/main/java/org/opensearch/common/annotation/PublicApi.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; + +/** + * 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 }) +public @interface PublicApi { + +} 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..8d582c83a974b --- /dev/null +++ b/libs/common/src/main/java/org/opensearch/common/annotation/package-info.java @@ -0,0 +1,14 @@ +/* + * 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 + */ +package org.opensearch.common.annotation; From 0dadd295d84813d9c740845c861dd9e4328505a8 Mon Sep 17 00:00:00 2001 From: Andriy Redko Date: Thu, 10 Aug 2023 12:59:41 -0400 Subject: [PATCH 2/4] Address code review comments Signed-off-by: Andriy Redko --- .../java/org/opensearch/common/annotation/PublicApi.java | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) 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 index 0b13899681854..80e7f66fc2a09 100644 --- a/libs/common/src/main/java/org/opensearch/common/annotation/PublicApi.java +++ b/libs/common/src/main/java/org/opensearch/common/annotation/PublicApi.java @@ -23,5 +23,8 @@ @Documented @Target({ ElementType.TYPE, ElementType.PACKAGE, ElementType.METHOD, ElementType.CONSTRUCTOR }) public @interface PublicApi { - + /** + * Version when this API was released + */ + String since() default ""; } From 71d10feb568c0d7de348be67c24c359ac420c1ca Mon Sep 17 00:00:00 2001 From: Andriy Redko Date: Thu, 10 Aug 2023 13:12:51 -0400 Subject: [PATCH 3/4] Address code review comments Signed-off-by: Andriy Redko --- .../java/org/opensearch/common/annotation/DeprecatedApi.java | 1 + .../java/org/opensearch/common/annotation/ExperimentalApi.java | 1 + .../main/java/org/opensearch/common/annotation/InternalApi.java | 1 + .../main/java/org/opensearch/common/annotation/PublicApi.java | 1 + .../main/java/org/opensearch/common/annotation/package-info.java | 1 + 5 files changed, 5 insertions(+) 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 index 3a4c1e527a79c..8661fd368bf1e 100644 --- a/libs/common/src/main/java/org/opensearch/common/annotation/DeprecatedApi.java +++ b/libs/common/src/main/java/org/opensearch/common/annotation/DeprecatedApi.java @@ -20,6 +20,7 @@ */ @Documented @Target({ ElementType.TYPE, ElementType.PACKAGE, ElementType.METHOD, ElementType.CONSTRUCTOR }) +@PublicApi public @interface DeprecatedApi { /** * Version since this API is deprecated 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 index dfa9c2dc8c4ae..f31ec5ec3826c 100644 --- a/libs/common/src/main/java/org/opensearch/common/annotation/ExperimentalApi.java +++ b/libs/common/src/main/java/org/opensearch/common/annotation/ExperimentalApi.java @@ -21,6 +21,7 @@ */ @Documented @Target({ ElementType.TYPE, ElementType.PACKAGE, ElementType.METHOD, ElementType.CONSTRUCTOR }) +@PublicApi 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 index 39c0a42464671..c5710672b58b4 100644 --- a/libs/common/src/main/java/org/opensearch/common/annotation/InternalApi.java +++ b/libs/common/src/main/java/org/opensearch/common/annotation/InternalApi.java @@ -20,6 +20,7 @@ */ @Documented @Target({ ElementType.TYPE, ElementType.PACKAGE, ElementType.METHOD, ElementType.CONSTRUCTOR }) +@PublicApi 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 index 80e7f66fc2a09..0de7dc10c6359 100644 --- a/libs/common/src/main/java/org/opensearch/common/annotation/PublicApi.java +++ b/libs/common/src/main/java/org/opensearch/common/annotation/PublicApi.java @@ -22,6 +22,7 @@ */ @Documented @Target({ ElementType.TYPE, ElementType.PACKAGE, ElementType.METHOD, ElementType.CONSTRUCTOR }) +@PublicApi public @interface PublicApi { /** * Version when this API was released 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 index 8d582c83a974b..72b747e35d964 100644 --- 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 @@ -11,4 +11,5 @@ * * @opensearch.api */ +@PublicApi package org.opensearch.common.annotation; From a54fda4ddf7cdee02209b2021d48ce2e75397e2d Mon Sep 17 00:00:00 2001 From: Andriy Redko Date: Thu, 10 Aug 2023 14:48:12 -0400 Subject: [PATCH 4/4] Address code review comments Signed-off-by: Andriy Redko --- .../java/org/opensearch/common/annotation/DeprecatedApi.java | 2 +- .../org/opensearch/common/annotation/ExperimentalApi.java | 2 +- .../java/org/opensearch/common/annotation/InternalApi.java | 2 +- .../main/java/org/opensearch/common/annotation/PublicApi.java | 4 ++-- .../java/org/opensearch/common/annotation/package-info.java | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) 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 index 8661fd368bf1e..08123e8e65f7f 100644 --- a/libs/common/src/main/java/org/opensearch/common/annotation/DeprecatedApi.java +++ b/libs/common/src/main/java/org/opensearch/common/annotation/DeprecatedApi.java @@ -20,7 +20,7 @@ */ @Documented @Target({ ElementType.TYPE, ElementType.PACKAGE, ElementType.METHOD, ElementType.CONSTRUCTOR }) -@PublicApi +@PublicApi(since = "2.10.0") public @interface DeprecatedApi { /** * Version since this API is deprecated 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 index f31ec5ec3826c..874763f9c9cff 100644 --- a/libs/common/src/main/java/org/opensearch/common/annotation/ExperimentalApi.java +++ b/libs/common/src/main/java/org/opensearch/common/annotation/ExperimentalApi.java @@ -21,7 +21,7 @@ */ @Documented @Target({ ElementType.TYPE, ElementType.PACKAGE, ElementType.METHOD, ElementType.CONSTRUCTOR }) -@PublicApi +@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 index c5710672b58b4..b2eec5c3ec431 100644 --- a/libs/common/src/main/java/org/opensearch/common/annotation/InternalApi.java +++ b/libs/common/src/main/java/org/opensearch/common/annotation/InternalApi.java @@ -20,7 +20,7 @@ */ @Documented @Target({ ElementType.TYPE, ElementType.PACKAGE, ElementType.METHOD, ElementType.CONSTRUCTOR }) -@PublicApi +@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 index 0de7dc10c6359..89faf44604195 100644 --- a/libs/common/src/main/java/org/opensearch/common/annotation/PublicApi.java +++ b/libs/common/src/main/java/org/opensearch/common/annotation/PublicApi.java @@ -22,10 +22,10 @@ */ @Documented @Target({ ElementType.TYPE, ElementType.PACKAGE, ElementType.METHOD, ElementType.CONSTRUCTOR }) -@PublicApi +@PublicApi(since = "2.10.0") public @interface PublicApi { /** * Version when this API was released */ - String since() default ""; + 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 index 72b747e35d964..7bb79d7579747 100644 --- 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 @@ -11,5 +11,5 @@ * * @opensearch.api */ -@PublicApi +@PublicApi(since = "2.10.0") package org.opensearch.common.annotation;