Checks#
Beyond the Maven build, CI runs a suite of repository-specific checkers — scripts under
scripts/ (mostly Python, some shell), most behind a just check-* recipe.
Several are deliberately two-way: they
hold the documentation to the source and the source to the documentation, so an option that
loses its table row fails the same check as a table row that loses its option. A contributor
meeting one for the first time should know that its failure message names the repair, and that
it is cheaper to run the relevant checker locally than to discover it on the pull request.
| Checker | What it holds |
|---|---|
just check-license-headers | Every Java source carries a complete copyright-bearing or canonical ASF Apache-2.0 header (stricter than apache-rat, and the first step of just verify — the only checker inside the build) |
just check-option-docs | Every connector option is documented, and every documented option is real |
just check-metric-docs | Every connector metric is documented, and every documented metric is real |
just check-flink-api-tiers | Main sources depend only on allowlisted Flink API stability tiers |
just check-javadoc-links | Javadoc member references resolve to the members they name, every public or protected member of a tier-annotated type carries Javadoc, and a ConfigOption constant’s Javadoc equals its runtime description (in-project targets; the checker states its own limits) |
just check-readme-examples / just check-doc-snippets | Source-backed Java examples stay synchronized with their tagged source regions and compile against the working tree; the first covers the module READMEs, while the second also builds the production Hugo site, adds the docs-page and Javadoc halves, and validates every source-backed Flink SQL region at its explicit boundary. A deliberately abbreviated Java example carries its classification marker and says so in prose |
just check-doc-sql-snippets | Every code block labeled sql in examples, quickstarts, and Table connector references is source-backed; each Flink SQL region reaches its command, catalog, planner, enclosed-fragment, or intentional-negative boundary, while GoogleSQL DDL and seed statements execute against the Spanner emulator |
just check-notice <module> / just check-notice-sources | A shaded jar’s generated NOTICE matches what it bundles, and the pinned licence texts still match what is served |
just check-gated-tags | Every credential-gated test carries both its environment gate and the tag that keeps it out of ordinary builds |
just lint / just test-scripts | The scripts, workflows and rendered Markdown — and the checkers’ own test suite. OpenTofu validation, formatting and TFLint run before each selected root’s plan |
just --list is the full index; the table stays at this altitude so it does not chase every
recipe change.
When a check fails#
Each checker with judgment calls in its repair pairs with a skill under
.agents/skills/ — a playbook that says what
a given failure message means, which responses are acceptable, and which decisions must go to a
maintainer. Coding agents load them by name; a human contributor can read them the same way.
The curate-* skills answer their checker’s failures (curate-option-docs,
curate-metric-docs, curate-flink-api-tier, curate-licence-source), the maintain-*
skills own the compiled documentation examples, add-a-connector-option covers everything a
new option owes, and the workflow skills (push-pr-branch, self-review,
self-review-round-two, independent-review, project-memory) encode the pull-request
process that Contributing describes.
just check-skill-frontmatter validates the skills themselves.