Motivation
At the moment we do not have any mechanism or strategy to guard how we deprecate CLI actions in the project, and if there are any guarantees that any CLI action will not be removed in a minor release. I am preparing this FLIP based on a previous discussion where we agreed that CLI actions are public, user-facing elements of the project, so it should not be allowed to remove them without giving time to the users to migrate and also providing some guidance about it.
To avoid introducing more maintenance work and complexity regarding when and how we can phase out specific elements of the project, a fairly simple idea is to apply the same Public API rules and deprecation policy that the project already defines for public programming APIs.
Public Interfaces
@Public
Modify the @Public annotation interface so we can mark fields and methods as well. Furthermore, add RUNTIME retention policy to be able to check if an element is annotated via reflection.
/**
* Annotation for marking classes, methods, and fields as public, stable interfaces.
*
* <p>Classes, methods, and fields with this annotation are stable across minor releases (1.0, 1.1,
* 1.2). In other words, applications using @Public annotated classes will compile against newer
* versions of the same major release.
*
* <p>Only major releases (1.0, 2.0, 3.0) can break interfaces with this annotation.
*/
@Documented
@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Public
public @interface Public {}
DeprecationMode
Add a new @Public annotated enum into flink-clients that defines the possible deprecation modes for CLI actions.
/** Controls how to handle deprecated CLI actions. */
@Public
public enum DeprecationMode {
/**
* Strict mode means using any deprecated CLI action is forbidden, so the execution will be
* blocked and an exception will be thrown. This helps to highlight users as soon as possible
* that they depend on or use deprecated elements.
*/
STRICT,
/**
* Compatible mode permits the usage of deprecated CLI actions, making it possible for users to
* gain some time to change their workflow accordingly. A warning message is displayed in this
* case as well.
*/
COMPATIBLE
}
CliFrontend
Give all CLI actions public visibility, and mark them as @Public as well.
@Public public static final String ACTION_RUN = "run"; @Public @Deprecated public static final String ACTION_RUN_APPLICATION = "run-application"; @Public public static final String ACTION_INFO = "info"; @Public public static final String ACTION_LIST = "list"; @Public public static final String ACTION_CANCEL = "cancel"; @Public public static final String ACTION_STOP = "stop"; @Public public static final String ACTION_SAVEPOINT = "savepoint"; @Public public static final String ACTION_CHECKPOINT = "checkpoint";
Configuration
Add new client configuration that controls whether we enforce to not use deprecated CLI actions:
public static final ConfigOption<DeprecationMode> CLIENT_DEPRECATION_MODE =
key("client.deprecation-mode")
.enumType(DeprecationMode.class)
.defaultValue(DeprecationMode.STRICT)
.withDescription(
Description.builder()
.text(
"Controls whether the client permits the usage of deprecated CLI actions."
+ " Defaults to 'strict'. Possible values:")
.list(text("strict"), text("compatible"))
.build());
Proposed Changes
Check deprecated CLI action usage in CliFrontend
Check the given action arg and validate against the existing CLI actions and if the action is @Deprecated, and DeprecationMode is STRICT as well, throw an exception to block the execution with a message about how to override this behavior via setting DeprecationMode to COMPATIBLE.
Even in compatible mode, a warning should be displayed to highlight the deprecated usage as much as possible, also giving guidance to check the CLI help or the documentation regarding what to use moving forward.
Compatibility, Deprecation, and Migration Plan
n/a
Test Plan
Add unit tests to the newly introduced annotation checker method.
Rejected Alternatives
n/a