[jira] [Created] (FLINK-39808) Tighten `FlinkVersion.isSupported()` to reject `@Deprecated` versions and restore the deprecate-and-raise-floor pattern

["Dennis-Mircea Ciupitu (Jira)" <ji...@apache.org>]

Dennis-Mircea Ciupitu created FLINK-39808:
---------------------------------------------

             Summary: Tighten `FlinkVersion.isSupported()` to reject `@Deprecated` versions and restore the deprecate-and-raise-floor pattern
                 Key: FLINK-39808
                 URL: https://issues.apache.org/jira/browse/FLINK-39808
             Project: Flink
          Issue Type: Improvement
          Components: Kubernetes Operator
    Affects Versions: kubernetes-operator-1.15.0
            Reporter: Dennis-Mircea Ciupitu
             Fix For: kubernetes-operator-1.16.0


h1. Summary

{{org.apache.flink.kubernetes.operator.api.spec.FlinkVersion}} carries two independent statements about which Flink versions are usable, and they currently disagree.
h2. The Two Statements

*Statement 1: the {{@Deprecated}} annotations on enum constants*

{{FlinkVersion.java}} marks early constants with javadoc deprecation notes:
 * {{v1_13}} - "No longer supported since 1.7 operator release"
 * {{v1_14}} - "No longer supported since 1.7 operator release"
 * {{v1_15}} - "Deprecated since 1.10 operator release"
 * {{v1_16}} - "Deprecated since 1.11 operator release"
 * {{{}v1_17{}}}, {{v1_18}} - {{@Deprecated}} with no javadoc note

*Statement 2: the runtime check {{isSupported()}}*
{code:java}
public static boolean isSupported(FlinkVersion version) {
    return version != null && version.isEqualOrNewer(FlinkVersion.v1_15);
}
{code}
This call is invoked from {{ValidatorUtils.validateSupportedVersion()}} and surfaces an {{UnsupportedFlinkVersion}} event when it returns {{{}false{}}}.
h2. The Contradiction

A user can deploy a {{FlinkDeployment}} with {{spec.flinkVersion: v1_15}} today. The runtime check accepts it (because {{v1_15.isEqualOrNewer(v1_15)}} is {{{}true{}}}), but the enum constant carries a deprecation notice saying the version is "Deprecated since 1.10 operator release". Same for {{{}v1_16{}}}, {{{}v1_17{}}}, {{{}v1_18{}}}.

This makes it impossible to document the supported-versions list honestly without either explaining the contradiction in user-facing text or one of the two statements changing in code.
h2. Historical Context

The project had a working pattern for handling Flink version deprecation, and the contradiction grew because subsequent commits stopped following it.

*The established pattern* ([FLINK-33089|https://github.com/apache/flink-kubernetes-operator/commit/02d8dd5d915b7d890d09c23c9003580ab63e6dc1] - "Clean up 1.13 and 1.14 references from docs and code"):

When {{v1_13}} and {{v1_14}} were retired, the commit did three things consistently:
 # Added {{@Deprecated}} with explicit javadoc notes ("No longer supported since 1.7 operator release") to both enum constants.
 # Updated {{isSupported()}} to raise the floor from {{v1_14}} to {{{}v1_15{}}}, so the runtime check rejected the now-deprecated versions.
 # Updated docs ({{{}overview.md{}}}, {{{}reference.md{}}}) to reflect the new supported set and surface the "no longer supported" notes for users.

All three statements agreed afterward.

*The drift* (two later commits):

[FLINK-37236|https://github.com/apache/flink-kubernetes-operator/commit/d6e20e22ff832abe644eee91d520238b230fa374] - "Bump Flink dependencies to 1.20 and add v2_0 version": Added new versions and removed older ones from the CI matrix, but did not update {{isSupported()}} or the runtime semantics for the versions being retired.

[FLINK-38147|https://github.com/apache/flink-kubernetes-operator/commit/b0274cb2ea724c758182401de2d77908f2a2271e] - "Add Flink 2.1 support": Added {{@Deprecated}} to {{v1_17}} and {{v1_18}} (without javadoc notes), added {{v2_1}} and {{{}v2_2{}}}, but again did not update {{{}isSupported(){}}}.

The result is the current contradiction: {{v1_17}} and {{v1_18}} carry {{@Deprecated}} but are still accepted at runtime, and {{{}v1_15{}}}/{{{}v1_16{}}} continue to be runtime-accepted despite the explicit "deprecated since X operator release" javadoc set in commit 1's era.
h2. Concrete Effects
 * The auto-generated table in {{docs/content/docs/custom-resource/reference.md}} shows {{v1_15}} and {{v1_16}} with "Deprecated since X operator release" notes, but no statement that they are actually still accepted at runtime.
 * The {{UnsupportedFlinkVersion}} event documented in {{docs/content/docs/operations/events.md}} only fires for versions older than {{v1_15}} (i.e. {{v1_13}} and {{{}v1_14{}}}). Users running deprecated-but-accepted {{v1_15}} through {{v1_18}} get no event, no warning, no log indication that they are on a version slated for removal.
 * The {{Compatibility}} docs page cannot include a "Supported Flink versions" section without a contradiction footnote.
 * New deprecations from {{v1_19}} onward will require a third manual update (annotation + {{isSupported()}} + docs) that contributors have already shown they will miss, perpetuating the drift.

h1. Proposed Resolution

Restore the pattern established in [FLINK-33089|https://github.com/apache/flink-kubernetes-operator/commit/02d8dd5d915b7d890d09c23c9003580ab63e6dc1]. The runtime check {{isSupported()}} should be the authoritative source of truth, deriving its decision from the {{@Deprecated}} annotation so that future deprecations propagate automatically without contributors having to remember three separate code sites.



--
This message was sent by Atlassian Jira
(v8.20.10#820010)