Run the PyAthena suite only when its files change

[laughingman7743]

WHAT

• Add a pyathena filter to the changes job in .github/workflows/test.yaml: the shared files (test.yaml, test-suite.yaml, justfile, pyproject.toml, uv.lock), setup.cfg, pyathena/**, and tests/**.
• Expose it as the pyathena job output, in the same form as sqla and spark: true for every event other than pull_request.
• Run the test job (the PyAthena suite) only when that output is true.
• The pyathena filter is a superset of sqla and spark, so the SQLAlchemy and Spark tests are never selected without the PyAthena suite.
• The trigger keeps paths-ignore. The lint job (just lint: ruff, mypy, license headers, cfn-lint) still runs for pull requests that change only benchmarks/, scripts/, or cloudformation/.
• docs/testing.md: the Ready pull request row now says the PyAthena suite runs when related files change, and lists its related files. The SQLAlchemy and Spark text now names the top-level modules and shared test fixtures that ci: run SQLAlchemy and Spark tests when shared core modules change #906 added to their selection, which the page did not mention.

WHY

Part of #911. The 3.x backport follows separately, and the issue stays open until it merges.

A Ready pull request that changes only files the PyAthena suite does not use still ran the suite against AWS.

TEST

Tested commit: 2c369bf for the workflow. The later commits up to 692d623 change only sentences of docs/testing.md, and just docs lint passes.

• Local simulation of dorny/paths-filter v4.0.3 (js-yaml load of the filters block, flattened anchors, picomatch dot: true, some quantifier):
  • 28 cases, 0 failures. pyathena/**, tests/**, setup.cfg, and the shared files select the PyAthena suite. benchmarks/**, scripts/**, cloudformation/**, NOTICE, LICENSE, .mise.toml, .github/workflows/release.yaml, and .github/workflows/benchmarks.yaml do not.
  • Invariant over every tracked file of master (279) and origin/3.x (236): no file selected by sqla or spark is unselected by pyathena.
• Replay of the changed files (including the previous names of renamed files) of the 104 pull requests merged into master since 2026-06-01. Six are docs/Markdown-only and start no run. Of the other 98, compared with master's filter, only these change selection, each from "PyAthena suite only" to no AWS suite:
  • Update gh-action-pypi-publish to v1.14.2 for metadata 2.5 support #765 (release.yaml), Add NOTICE acknowledging PyHive's influence #802 (NOTICE), Run benchmark jobs on a fleet of identical hosts #823, Count initialization row validation as API-heavy fleet work #824, Allow Graviton benchmark hosts with an architecture parameter #827 (benchmarks/), as listed in the issue.
  • Sweep leaked test databases daily with a one-day cutoff #907 (database-sweep.yaml, scripts/sweep_databases.py and its tests, docs/testing.md), merged on 2026-10-01 shortly before the issue was filed and missing from its list. Its script and tests run in the separate Scripts workflow (just scripts).
• just lint, actionlint .github/workflows/test.yaml, just docs lint: pass.
• No AWS tests were run locally. This pull request changes test.yaml, so its Ready run 36801176633 on 692d623 selected every suite. The changes log shows Filter pyathena = true and Changes output set to ["shared","sqla","spark","pyathena"]; test, test-sqla, and test-sqla-async (Python 3.14) passed. No live run with pyathena=false exists yet; that case is covered only by the simulation.

🤖 Generated with Claude Code

[laughingman7743]

Self-review round one (implementation behavior): FINDINGS, repaired

• Scope: full pass over git diff 468affc6417840912fd58b37712214c3a493edc3..2c369bf670a43bb65a36c26fbe38c1fb29d082e8, two files: .github/workflows/test.yaml (new pyathena filter, pyathena job output, if: on test, changes comment) and docs/testing.md (GitHub Actions section).
• Behavior:
  • The output has the same form as sqla/spark, so it is the string true/false. For non-pull_request events the paths step is skipped and the output is true, so schedule, dispatch, and Release runs still select the suite. Inside the workflow_call from release.yaml, github.event_name is the caller's tag push, and release (needs: test) still waits on every suite.
  • Draft and fork PRs: changes is skipped, so test is skipped as before. A false output now skips test too; test-sqla/test-sqla-async do not depend on test, and master has no required status checks, so a skipped job blocks nothing.
  • dorny v4.0.3 sets <key>, <key>_count, and changes outputs per filter key (main.ts lines 273-285); pyathena collides with none of them. The comment lines inside filters parse as YAML comments, as in ci: run SQLAlchemy and Spark tests when shared core modules change #906.
  • skip-spark/skip-sqla inputs are unchanged. When test runs, they behave as before.
• Superset: pyathena = shared + setup.cfg + pyathena/** + tests/**, which covers every core, sqla, and spark pattern. The simulation's invariant over all tracked files on master (279) and 3.x (236) holds.
• What the suite reads: just tox (tox config in pyproject.toml) → uv sync --group dev (uv.lock) + just test pyathena (justfile, lint first) over tests/pyathena/. The benchmarks workspace member reaches it only through uv.lock. No test reads scripts/, cloudformation/, or benchmarks/ (grep).
• Finding (repaired in dfc14e2): docs/testing.md still said marking the Draft ready "starts the AWS jobs". With this change it may start none, so the sentence now says "the selected AWS jobs".
• Simplicity: no *core in pyathena, because pyathena/** and tests/** already contain it.
• Checks after the repair: just docs lint passes; earlier just lint and actionlint pass.

[laughingman7743]

Self-review round two (claims and operational effects): FINDINGS, repaired in the PR description

• Scope: full claim audit of git diff 468affc6417840912fd58b37712214c3a493edc3..dfc14e24ae3003a4418aa90b3bed2c607ea0027c (workflow comments, docs/testing.md, both commit messages, the PR body) and the issue premises it repeats.
• Finding (repaired in the PR body): it said Sweep leaked test databases daily with a one-day cutoff #907 merged after CI runs the PyAthena suite for pull requests that change no file it uses #911 was filed. Sweep leaked test databases daily with a one-day cutoff #907 merged at 2026-10-01T00:02:34Z, and CI runs the PyAthena suite for pull requests that change no file it uses #911 was created at 00:31:36Z. The body now says Sweep leaked test databases daily with a one-day cutoff #907 merged shortly before the issue and is missing from its list.
• Claims checked:
  • lint still runs for PRs that change only benchmarks/, scripts/, or cloudformation/: the trigger's paths-ignore is unchanged (docs/**, **.md) and lint has no if.
  • Sweep leaked test databases daily with a one-day cutoff #907's script and tests are covered elsewhere: scripts.yaml triggers on scripts/** and .github/workflows/** and runs just scripts, which runs pytest scripts/tests/.
  • Replay: gh pr list --search merged:>=2026-06-01 returns 104 PRs. The six docs/Markdown-only ones (Add a security policy #748, Add shared instructions for Codex and Claude Code #749, Pin the CI test badge to the master branch #766, Add shared development and review skills for Codex and Claude Code #778, Define contribution, AWS validation, and attribution requirements #788, Fix PandasCursor performance tuning examples #902) start no run. Of the other 98, exactly Update gh-action-pypi-publish to v1.14.2 for metadata 2.5 support #765, Add NOTICE acknowledging PyHive's influence #802, Run benchmark jobs on a fleet of identical hosts #823, Count initialization row validation as API-heavy fleet work #824, Allow Graviton benchmark hosts with an architecture parameter #827, and Sweep leaked test databases daily with a one-day cutoff #907 change selection, each from the PyAthena suite alone to no AWS suite.
  • "Their tests never run without the PyAthena suite" (filter comment): sqla/spark true implies pyathena true for every tracked file (simulation invariant), and for a PR's file set because each filter is an any-match.
  • Docs: the table row, the PyAthena related files, and "run all three" match the filters, including the core paths that ci: run SQLAlchemy and Spark tests when shared core modules change #906 added. The comment's short list ("the dependencies, or this workflow") follows the existing SQLAlchemy/Spark sentence; the exact list is the filters block below it and the docs. Deferred as wording, not behavior.
  • "Once Ready its own run selects every suite": the PR changes .github/workflows/test.yaml, which is in shared.
• Operator: fewer AWS runs only. A file missing from the allowlist is still tested by the weekly schedule and the Release workflow, whose pyathena output is always true.
• Evidence limits: selection is checked by a local re-implementation of dorny v4.0.3 matching, not by GitHub. The PR's own run selects every suite, so no live pyathena=false run exists until a later PR that changes only unlisted files.

[laughingman7743]

Independent review (relayed): FINDINGS, repaired in e737245

• Reviewer: Codex CLI 0.157.1, model gpt-6-sol, reasoning effort high, --sandbox read-only, --ephemeral, session 01a0f50c-0ba1-7f92-982e-a63e640c8436. Static review only: no workflow or tests run.
• Scope: full pass over 468affc6417840912fd58b37712214c3a493edc3..dfc14e24ae3003a4418aa90b3bed2c607ea0027c on a detached snapshot. Because the sandbox has no network, the package also contained action.yml, src/main.ts, and src/filter.ts of dorny/paths-filter at the pinned commit ceb8a2b8 (v4.0.3), outside the repository tree. The prompt omitted the PR number, description, commit messages, and prior findings. The snapshot's HEAD was unchanged afterwards; the only untracked entry was that reference directory.
• Covered: the Test and Release workflow gates, the pinned action's parser and matching, the reusable suite, the test commands and fixtures, and docs/testing.md.
• Finding (introduced, verified, repaired): docs/testing.md:165 said "When the SQLAlchemy or Spark tests do not run, the PyAthena suite runs without them." For a Ready PR that changes only scripts/check_license_headers.py, the run starts and lint runs, but all three AWS suites are skipped, so the sentence implied a PyAthena run that does not happen. It now reads "When the PyAthena suite runs but the SQLAlchemy or Spark tests do not, it runs without them."
• Otherwise: the pyathena filter matches the specified paths and is a superset of sqla and spark. The output and the if: keep schedule, dispatch, and Release runs, and a skipped or failed changes does not start test. The reviewer found no other introduced or pre-existing issue in scope.

[laughingman7743]

Repair self-review (both perspectives): CLEAN

• Scope: git diff dfc14e24ae3003a4418aa90b3bed2c607ea0027c..e737245e6ecabe1f77660e19ff6153d906933c28, one sentence of docs/testing.md.
• Behavior: documentation only; no workflow change.
• Claim: when test runs with skip-sqla/skip-spark true, test-suite.yaml adds --ignore for those test directories to PYTEST_ADDOPTS, so "it runs without them" holds.
• Related prose: a search of docs/, README.md, CONTRIBUTING.md, AGENTS.md, .agents/, and .github/ finds no other statement that the PyAthena suite always runs. Line 170 was already scoped to "the selected AWS jobs" in round one.
• Check: just docs lint passes.

[laughingman7743]

Independent follow-up 1 (relayed): FINDINGS, repaired in 692d623

• Reviewer: Codex CLI 0.157.1, gpt-6-sol, effort high, read-only, ephemeral, session 01a0f50c-... → follow-up session 01a0f50e-b944-7bd0-a43e-507edcd7a0e8. Static review of the repair dfc14e24..e737245e and the GitHub Actions section of docs/testing.md, against test.yaml and test-suite.yaml.
• Result: the repair at line 165 resolves the earlier finding and is accurate.
• New finding (verified, repaired): line 170 said marking the Draft ready "starts the selected AWS jobs". A Ready PR that changes only scripts/check_license_headers.py starts none. It now says "starts any AWS jobs its changed files select".

[laughingman7743]

Repair self-review (both perspectives) and independent follow-up 2 (relayed): CLEAN

• Self-review of e737245e6ecabe1f77660e19ff6153d906933c28..692d623dc57bc9ef4d1a03021e8eab686dc06752 (one sentence): documentation only. "Any" covers both outcomes: a PR that changes only unlisted files starts no AWS job, and one that changes listed files starts the selected suites. The cancellation half of the sentence is unchanged. just docs lint passes.
• Codex follow-up 2: same reviewer settings, session 01a0f50f-92d8-7563-ac95-db3c7e567b6e, static review of the repair and docs/testing.md:150-190 against test.yaml and test-suite.yaml. Result: CLEAN. The reported case now selects no AWS jobs, and the section is consistent.
• After each run, the snapshot's HEAD matched the reviewed commit; its only untracked entry was the reference directory.