weiqingy opened a new pull request, #971: URL: https://github.com/apache/flink-agents/pull/971
Linked issue: #894 ### Purpose of change Fills the `docs-only` row that #911 left as `planned`, the third of the four per-change-type guides. #957 filled the `Python-Java bridge` row the same way, and #961 is the `api/` row. #### Runtime flow No executable path changes. The flow this PR completes is the routing one that #911 introduced. A reviewer opens a documentation PR, reads the Change-Type Review Guides table in `code_review.md`, and follows the row matching the change. Before this PR the `docs-only` row terminated at the word `planned`, so the reviewer fell back to the general passes, which are written for code. After it, the row resolves to `review-guides/docs-only.md`, which narrows the passes to this change type and then hands back to the general ones. #### Key decisions The `Validation` section leads with a negative fact rather than a command list, because for this change type that is the useful content. A change under `docs/content` runs the full CI matrix and passes without any job reading a changed line. `ci.yml` has no path filter so every job runs, ruff runs with `python/` as its root, and the site build lives in `docs.yml`, triggered on a schedule and by manual dispatch rather than on pull requests. There is no markdown linter and no link checker in the repo. A guide that listed commands here would be inventing them. No local site-build command is published. `tools/docs.sh` mutates global git config with a container-only path, fetches a Linux x86-64 Hugo binary, and needs the theme submodule initialized, so it is not something a reviewer can be told to run. The checklist is five bullets rather than the sibling's six. A sixth was drafted, covering pages that document a feature without naming its language scope, and cut when its evidence proved wrong: every section I had flagged does carry a scope hint, in a phrasing variant my original search missed. Nothing was added back to restore the count. Both example rows cite docs findings raised on merged, genuinely documentation-only PRs, so neither row illustrates its change type with a PR of a different type. ### Implementation Description #### Behavioral contracts The guide is prose, so its contracts are the claims it makes about this repository. Each is separately checkable. 1. No CI job reads any file under `docs/content`. 2. The site build is triggered on a schedule and by manual dispatch, not on pull requests. 3. Ruff runs with `python/` as its root, so it does not reach `docs/`. 4. No link checker runs anywhere in the repository. 5. Nothing compiles, imports, or runs the code inside a documentation page. 6. `weight` orders a page among the pages it sits beside. 7. Each of the two cited review threads raised what the guide's table says it raised. #### Failure behavior There is no runtime failure path. The failure mode is a wrong claim, and nothing in CI would catch one: RAT excludes `docs` and `review-guides`, no markdown linter exists, and the relative link in `code_review.md` is checked by nothing. That makes a false sentence here worse than a false sentence in a comment, because it is guidance a reviewer acts on. One such claim did occur and is worth stating. An earlier draft said no CI job reads anything under `docs/`. That is false: `SchemaParityTest` and `test_specs.py` both read `docs/yaml-schema.json`, so a PR touching only that file is documentation-only by path and is validated byte for byte. Contract 1 is now scoped to `docs/content`, verified separately, with the only references to that path outside the subtree being Hugo's own settings in `docs/config.toml`. One consequence I did not try to solve here: a `docs/yaml-schema.json` PR is docs-only by path, so the table routes it to this guide, which is then the wrong guide for it. That seems better settled once the remaining rows are filled than by carving an exception into this one. ### Tests Not applicable in the executable sense, documentation only, no logic. `./tools/check-license.sh` passes. No license header is needed: `tools/.rat-excludes` covers `review-guides/`, and `.licenserc.yaml` ignores `**/*.md`. Each contract above was verified against source rather than written from memory. | Contract | How it was checked | |---|---| | 1. No CI job reads `docs/content` | Grepped all workflows, `tools/`, and every `.java`, `.py`, `.sh` for `docs/content` and `content.zh`. Only hits are `docs/config.toml`, consumed by `tools/docs.sh` from `docs.yml` alone | | 2. Site build trigger | `docs.yml`'s `on:` block is `schedule` plus `workflow_dispatch`, no `pull_request` | | 3. Ruff root | `tools/lint.sh`, on both its uv and pip paths | | 4. No link checker | Searched all workflows and config, zero hits | | 5. Page code never run | `tools/lint.sh`, `tools/ut.sh`, ruff config, pytest config for `addopts` and `doctest_glob` | | 6. `weight` ordering | Documented at `docs/README.md` | | 7. Both review threads | Both comment bodies re-fetched through the API, both PRs confirmed merged and confirmed docs-only | ### API No. No code or public API change, and no compatibility impact for any caller. For a reader, one row of the `code_review.md` table changes from `planned` to a link. The two already-linked rows and the two still `planned` are untouched, and the Focus cell wording is unchanged from #911. ### Documentation - [x] `doc-included` ### Was this patch authored or co-authored using generative AI tooling? - [x] Yes `Generated-by: Claude Code 2.1.223` -- 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]
