Skip to content

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

@reta

Description

@reta

Is your feature request related to a problem? Please describe.
It would make sense to start with this 4 annotations (please see their description for the guarantees)

Describe the solution you'd like

/**
 * Stable public APIs that retain source and binary compatibility within a minor 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.
 */
@Documented
@Target({ ElementType.TYPE, ElementType.PACKAGE, ElementType.METHOD, ElementType.CONSTRUCTOR })
public @interface PublicApi {

}
/**
 * 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.
 */
@Documented
@Target({ ElementType.TYPE, ElementType.PACKAGE, ElementType.METHOD, ElementType.CONSTRUCTOR })
public @interface ExperimentalApi {

}
/**
 * Internal APIs that have no compatibility guarantees and should not be used outside
 * of OpenSearch core components.
 */
@Documented
@Target({ ElementType.TYPE, ElementType.PACKAGE, ElementType.METHOD, ElementType.CONSTRUCTOR })
public @interface InternalApi {

}

/**
 * Marks the public APIs as deprecated and scheduled for removal in one of the upcoming
 * major release. The types marked with this annotations could only be other {@link PublicApi}s.
 */
@Documented
@Target({ ElementType.TYPE, ElementType.PACKAGE, ElementType.METHOD, ElementType.CONSTRUCTOR })
public @interface DeprecatedApi {
    String since();
    String forRemoval();
}

Describe alternatives you've considered
N/A

Additional context
Part of #8127

Metadata

Metadata

Assignees

No one assigned

    Labels

    APIIssues with external APIsenhancementEnhancement or improvement to existing feature or requestv2.10.0

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions