Backport #913: Run the PyAthena suite only when its files change

[laughingman7743]

WHAT

Backport #913 to the 3.x maintenance branch. It is one -x commit, cherry-picked from master's merge commit 7e8616f (git cherry-pick -m 1 -x).

• The Test workflow's changes job gains a pyathena filter: the shared files (test.yaml, test-suite.yaml, justfile, pyproject.toml, uv.lock), setup.cfg, pyathena/**, and tests/**. The test job (the PyAthena suite) runs only when it matches.
• It is a superset of sqla and spark, so the SQLAlchemy and Spark tests never run without the PyAthena suite.
• Schedule, dispatch, and Release runs still select every suite. The trigger keeps paths-ignore, so the lint job (just lint, which on 3.x is ruff and mypy) still runs for every pull request the trigger admits.
• docs/testing.md: the GitHub Actions section describes the new selection and the shared core paths that ci: run SQLAlchemy and Spark tests when shared core modules change #906/Backport #906: Run SQLAlchemy and Spark tests when shared core modules change #910 added.

The merge commit applies without conflicts, and its added and removed lines match #913 exactly. The changed lines of the docs/testing.md section are identical to master; the rest of that section keeps its existing 3.x text.

WHY

Part of #911, which asked for the same change on 3.x after master. On 3.x, a ready pull request that changes only files such as benchmarks/, scripts/, or .github/workflows/release.yaml still runs the PyAthena suite against AWS.

Release: CI only, no release-note entry.

TEST

Tested commit: 93247b6.

• just lint (ruff, mypy), actionlint .github/workflows/test.yaml, and just docs lint: clean.
• Local simulation of dorny/paths-filter v4.0.3 matching (js-yaml load of the filters block, picomatch dot: true) against this branch's workflow:
  • The 28 cases from Run the PyAthena suite only when its files change #913 all match.
  • Over 3.x's 236 tracked files, no file selected by sqla or spark is unselected by pyathena. Unselected non-docs files: benchmarks/2018*/2022*, scripts/cloudformation/, scripts/worktree-env.sh, .github/workflows/{docs,docs-lint,docs-trigger,pinact,release}.yaml, .gitignore, .markdownlint-cli2.jsonc, .mise.toml, LICENSE, and Markdown.
• Replay of the three pull requests merged into 3.x (Backport CI and SQLAlchemy changes to 3.x for v3.37.0 #893, Backport #839: Resolve the bare awsathena scheme to the REST dialect #903, Backport #906: Run SQLAlchemy and Spark tests when shared core modules change #910): none changes selection.
• AWS: Ready run 36890311210 on 93247b6 (Python 3.14). This PR changes test.yaml, so every suite was selected: the changes log shows Filter pyathena = true and Changes output set to ["shared","sqla","spark","pyathena"]. test, test-sqla, and test-sqla-async passed.

🤖 Generated with Claude Code

[laughingman7743]

Self-review round one (implementation behavior): CLEAN

• Scope: full pass over git diff 0397685561081561b4da6b2dcc2c4f8fac3ad175..93247b6fda14ab34bbd3c340e8ad1e1fae402836, two files: .github/workflows/test.yaml and docs/testing.md.
• Faithfulness: the added and removed lines are identical to Run the PyAthena suite only when its files change #913's merge delta (7e8616fa^1..7e8616fa). The cherry-pick applied without conflicts.
• Behavior on 3.x:
  • test.yaml here matches master's except for the missing license header and PYTHON_VERSIONS with 3.10, so the output, the filter, and the if: behave as on master. Non-pull_request events produce pyathena=true.
  • release.yaml calls test.yaml from a v* tag push and release has needs: test, so a release still runs every suite.
  • test-suite.yaml keeps the same skip-sqla/skip-spark inputs, so a running PyAthena suite still ignores those directories as before.
  • The 3.x branch protection has no required checks, so a skipped test blocks nothing.
• What the suite reads on 3.x: tox in pyproject.toml runs uv sync --group dev and just test pyathena (just lint = ruff and mypy, then pytest on tests/pyathena/). 3.x has no uv workspace. benchmarks/ is excluded from ruff, mypy, and pytest collection. No test or recipe reads scripts/cloudformation/. Nothing outside the allowlist feeds the suite.
• Simulation against this branch's workflow: the 28 cases from Run the PyAthena suite only when its files change #913 all match. The superset invariant holds over the 236 tracked files.
• Simplicity: none to apply; the backport keeps master's text verbatim.

[laughingman7743]

Self-review round two (claims and operational effects): CLEAN

• Scope: full claim audit of git diff 0397685561081561b4da6b2dcc2c4f8fac3ad175..93247b6fda14ab34bbd3c340e8ad1e1fae402836 as it reads on 3.x: the workflow comments, the docs/testing.md GitHub Actions section, the commit message, and the PR body.
• Claims checked against 3.x, not master:
  • just lint on 3.x is ruff, ruff format, and mypy (justfile). There is no cfn-lint or license-header check, so the PR body names only ruff and mypy.
  • Draft cancellation (docs/testing.md:90) depends on converted_to_draft in the trigger, which 3.x has (test.yaml:9).
  • The fixtures the docs name, tests/pyathena/conftest.py and tests/resources/, exist on 3.x. tests/pyathena/tables.py is a no-op pattern here, as in Backport #906: Run SQLAlchemy and Spark tests when shared core modules change #910.
  • The unselected non-docs files listed in the PR body match the simulator's output for the 236 tracked files.
  • Replay: gh pr list --base 3.x --state merged returns exactly Backport CI and SQLAlchemy changes to 3.x for v3.37.0 #893, Backport #839: Resolve the bare awsathena scheme to the REST dialect #903, and Backport #906: Run SQLAlchemy and Spark tests when shared core modules change #910. Compared with 3.x's current filter, none changes selection.
  • "Applies without conflicts and matches Run the PyAthena suite only when its files change #913 exactly": the delta comparison came out identical.
• Operator: on 3.x only pull requests that touch none of the allowlisted files lose their PyAthena run, for example benchmarks/ or scripts/cloudformation/. Release tag runs and dispatch still run every suite. 3.x has no weekly schedule of its own, because cron runs only on the default branch. A file missing from the allowlist would therefore surface on 3.x at the next release tag run, or through a dispatch.
• Evidence limits: the selection is checked by local simulation. The Ready run of this PR will select every suite because it changes test.yaml.

[laughingman7743]

Independent review (relayed): CLEAN

• Reviewer: Codex CLI 0.157.1, model gpt-6-sol, reasoning effort high, --sandbox read-only, --ephemeral, session 01a0f833-d953-7963-aa72-417ccea50be3. Static review only: no build or tests run.
• Scope: full pass over 0397685561081561b4da6b2dcc2c4f8fac3ad175..93247b6fda14ab34bbd3c340e8ad1e1fae402836 on a detached snapshot, compared with master's merge commit 7e8616fa. The package also contained the pinned dorny/paths-filter v4.0.3 source (ceb8a2b8) outside the repository tree. The prompt omitted the PR number, description, and prior findings. After the run, the snapshot's HEAD was unchanged; its only untracked entry was that reference directory.
• Covered: test.yaml, test-suite.yaml, release.yaml, the pinned action source, the 3.x justfile, the tox configuration, the tests and fixtures, and the GitHub Actions section of docs/testing.md.
• Result: the backport matches the master delta. The filter covers the suite's test, configuration, and fixture paths on 3.x, and sqla/spark imply pyathena. Draft and fork PRs skip the AWS jobs. Schedule, dispatch, and the Release call select test, and release (needs: test) still waits on it. The comments and docs are accurate for 3.x. No introduced or pre-existing findings.