[infra] Derive and validate the Flink versions tools/ut.sh uses

[weiqingy]

Linked issue: #1006

Purpose of change

tools/ut.sh said omitting -f tests every supported Flink version. It tests one. The default was pinned to 2.2 while the root pom carries 2.3.0, so a bare run tested Java on 2.3.0 and Python on 2.2.x at once. -f was half-wired on top of that: it reached the e2e and Python tests, but nothing on the Java unit-test path reads it.

• Derive the default from the root pom's <flink.version> instead of pinning it, so both lanes agree and the value cannot drift again. tools/update_flink_version.sh bumps poms and never touches this script, which is how the literal fell behind. Validated as x.y before use, since it flows into module paths, profile names and the pip requirement.
• Scope -f to the e2e tests and reject it without -e. Unit tests stay where they were: each Java module on the <flink.version> its own pom resolves, Python on the root pom's. No caller in the repo passes -f without -e.
• Validate what -f accepts. -f 9.9 used to ask Maven for a module that does not exist, so a typo looked like it worked. The supported set now comes from the dist/flink-* modules rather than a second hardcoded list. This also adds the missing flink-2.3 e2e profile, which -f 2.3 previously hit by fallthrough after Maven warned and ignored it. The profile omits flink.log4j2.version on purpose: its siblings pin 2.24.3 because they need a value different from the parent's, and 2.3 needs the parent's.

Subsumes #1008.

The issue's other option, iterating every version by default, is not implementable today: runtime fails test-compile at 1.20 because RescalingTest.java imports Flink 2.x-only packages. It would also multiply every Java unit-test job by roughly five, to duplicate what the java_it_tests matrix already covers.

Tests

Three bats files, 25 cases, in the harness CI already runs. Subprocess and shim patterns from help.bats and dry_run.bats; none sources ut.sh, which has no run guard.

They cover the derived default (that it follows a changed pom, and the malformed shapes that must be fatal), the -f rejection (its condition and each clause of its message, so a clause rewritten into something false fails), and version validation against a fake dist/. One case asserts the help text shows no -f form the script would reject. One guards the three lists that must agree, whose disagreement is what left 2.3 without a profile.

Full harness 216 ok / 1 not ok. The failure is pre-existing and unrelated (verify_example_job.bats via test_submit_examples_to_flink.sh:362, remaining_pids[@] unbound); it reproduces on unmodified main. ./tools/ut.sh -p on the new default: 825 passed, 13 skipped, exit 0, on apache-flink 2.3.0 confirmed from the environment.

One behavior change: the Python unit-test jobs in ci.yml and build_wheel.yml now install apache-flink~=2.3.0 rather than ~=2.2.0, the current PyPI latest. Both integration matrices pass -e -f explicitly and are unaffected. Not covered: the pip fallback branch of ut.sh -p.

API

No public API change. The observable change is to the script's CLI behavior and help text, described above.

Documentation

• doc-needed
• doc-not-needed
• doc-included

Every inaccurate claim was in the script's own help text, which this PR corrects. No file under docs/ references tools/ut.sh.

Was this patch authored or co-authored using generative AI tooling?

• Yes
• No

Generated-by: Claude Code 2.1.229 (Claude Opus 5)

[wenjin272]

Thanks for the update. Deriving the default Flink version from the root POM looks good.

One concern with the current CLI contract is that -f affects Python unit tests but not Java unit tests. Since CI runs UTs only against the default version and uses the E2E/IT matrix for multi-version coverage, could we scope -f to E2E tests only? Both Java and Python UTs would then consistently use the root POM version, and -f without -e could be rejected with a clear error.

The current examples should also be updated:

$0 -f 2.2  # Run tests only for Flink 2.2

This is not accurate because Java UTs still use the root POM version. If -f is E2E-only, the example could use -e -f 2.2 instead.

[weiqingy]

@wenjin272 Thanks, that is a better contract. Done in 32a90b0.

-f now selects the Flink version the e2e tests run against and nothing else, and passing it without -e exits 1 with an error naming the remedy. The warning is gone, since the case it warned about no longer exists. Nothing in the repo invokes -f without -e, so no CI job or documented command changes. The one thing it removes is ./tools/ut.sh -p -f 2.2, running the Python unit tests against a non-default PyFlink, which nothing here uses.

Examples fixed. There were two more carrying the same problem that I had missed: the inline Examples: -f 2.3, -f 1.20, -f 2.3 -f 1.20 line inside the -f block, and the missing-argument hint (e.g., -f 1.20). All three are -e -f forms now, and a test asserts the script demonstrates no -f form it would itself reject, so a future example cannot reintroduce one.

One correction on the wording while implementing it. "Both Java and Python UTs would then consistently use the root POM version" turns out not to hold for Java. The dist/flink-* modules stay in the unit-test reactor, since only the two e2e modules are excluded, and each of them pins its own version. dist/flink-1.20 is the only dist module with a test, and it runs at 1.20.5. So the help text now says the unit tests cannot be retargeted by -f, and that each Java module builds against the <flink.version> its own pom resolves, rather than naming one version for both lanes.