weiqingy opened a new pull request, #961: URL: https://github.com/apache/flink-agents/pull/961
Linked issue: #894 ### Purpose of change Continues item 2 of #894 by filling the `api/` contract row that #911 left as `planned`. This is the third guide, after the merged `runtime-state-recovery.md` and the `Python-Java bridge` one currently open as #957. `review-guides/api-contract.md` follows the same shape as both: a focused checklist that narrows the full passes in `code_review.md`, and two examples drawn from real review threads on merged PRs, each linking the specific comment. The six bullets are ordered by how often a reviewer will hit one, and each names a failure that is silent in this repo rather than one the build catches. A new integration whose YAML alias was never added still resolves, because both loaders pass an unrecognized name through unchanged. A config option added on the Java side only passes every fast CI job, since the bidirectional parity check runs solely in the cross-language lane. A doc that contradicts the code ships green, because nothing in pull request CI builds the doc site. One bullet is worth calling out because it removes work rather than adding it. The row's Focus text names deprecation, but there is no deprecation mechanism in this repo, so the question a reviewer should be asking is whether a removal is complete, not whether something should be deprecated first. I left the Focus cell alone and addressed it in the guide instead. It carries a `Validation` block, like #957 and unlike the merged guide. Two of its five commands are the reason it is there: `ConfigOption` parity and `ResourceName` parity are standalone scripts rather than tests, so neither `mvn test -pl api` nor `pytest flink_agents/api` reaches them, and today they run only behind the Docker-backed e2e lane. Both finish in well under a second when invoked directly. That block is why this guide is 72 lines against the merged sibling's 31. The checklist itself is the same six bullets; the difference is five commands instead of two. The remaining two rows, `dist` and docs-only, stay `planned` and will follow the same way. One practical note: #957 flips the adjacent row in the same table, so whichever lands second will need a trivial rebase. ### Tests Not applicable, documentation only, no logic. `./tools/check-license.sh` passes. No license header is needed, since `tools/.rat-excludes` already covers `review-guides/` and `.licenserc.yaml` ignores `**/*.md`. Every checklist claim was checked against source rather than written from memory, and several drafts were discarded when the source disagreed. The claim about cross-language snapshots was verified by experiment rather than by reading: adding a field to a built-in event on both sides and regenerating only the Java snapshots fails exactly one test, the Python side's own stability test, while its cross-read counterpart still passes. Adding the field on the Java side only and regenerating fails nothing at all, across 292 Java and 450 Python tests. Both of those outcomes are what the bullet now says. All five published commands were executed. Flags that made no difference were removed rather than left in for safety, including `-Dspotless.skip=true`, since spotless runs and passes and skipping it would hide a real CI failure. The two that remain were each confirmed load-bearing. No Flink version is pinned anywhere in the block. Three files in the repo currently disagree on the default, so the unpinned install was verified against both 2.2.1 and 2.3.0. Both review permalinks were re-fetched and both cited PRs re-confirmed merged. The relative link was checked by hand, since no workflow in this repo validates markdown or checks links. ### API No. No code or public API change. ### Documentation - [ ] `doc-needed` - [ ] `doc-not-needed` - [x] `doc-included` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
