Skip to content

ci: ungated check-only Lint workflow (ruff + black) + blame-ignore + docs#681

Merged
igerber merged 1 commit into
mainfrom
ci/lint-workflow
Jul 12, 2026
Merged

ci: ungated check-only Lint workflow (ruff + black) + blame-ignore + docs#681
igerber merged 1 commit into
mainfrom
ci/lint-workflow

Conversation

@igerber

@igerber igerber commented Jul 12, 2026

Copy link
Copy Markdown
Owner

Summary

  • New .github/workflows/lint.yml: check-only (never modifies code) ruff check diff_diff tests + black --check diff_diff tests at the versions pinned in the dev extra (chore: pin lint tooling + normalize source and hand-fixed test files (1/2) #677). Runs ungated on every PR push (precedent: ai_pr_review.yml) plus pushes to main to catch merge-skew; deliberately no paths: filter (a required check whose workflow never triggers blocks PRs forever on "Expected"). Actions SHA-pinned per repo convention; top-level permissions: contents: read; concurrency-cancel per PR.
  • Aggregate Lint Gate job (needs: [format-lint], if: always(), fails unless every upstream result is success) gives branch protection a single stable required-check name. if: always() is load-bearing: a skipped required check counts as satisfied on GitHub, so the gate must run and inspect results explicitly. The planned mypy job (next PR in this program) will extend needs with no protection change.
  • .git-blame-ignore-revs listing the chore: pin lint tooling + normalize source and hand-fixed test files (1/2) #677/chore: mechanical black/ruff normalization of remaining test files (2/2) #679 normalization squash SHAs (the chore: pin lint tooling + normalize source and hand-fixed test files (1/2) #677 squash also carries that PR's small hand fixes - noted in the file comment as an accepted squash-convention trade-off).
  • CONTRIBUTING.md gains a "Linting and Formatting" section (pinned-where, sync contract, deliberate per-file-ignores, stale-branch rebase guidance); CLAUDE.md commands section gains the matching note.

Post-merge handoff (manual, one-time)

After this merges and the Lint workflow has run green on main: add Lint Gate to the required status checks for main in branch protection. No further protection change will be needed when the mypy job is added.

Methodology references (required if estimator / math changes)

  • Method name(s): N/A - CI/docs only, no diff_diff/ changes
  • Paper / source link(s): N/A
  • Any intentional deviations from the source (and why): None

Validation

  • Tests added/updated: none needed; full tests/test_openai_review.py -m '' run green (250 passed - the workflow-guard suite; all its classes are scoped to named workflow files, so the new lint.yml violates nothing). YAML parse verified; blame-ignore attribution smoke-tested (git -c blame.ignoreRevsFile=... blame on a reformatted file attributes to the pre-normalization commit); ruff check + black --check clean on this tree, so the workflow dogfoods green on this very PR.
  • Backtest / simulation / notebook evidence (if applicable): N/A

Security / privacy

  • Confirm no secrets/PII in this PR: Yes

Generated with Claude Code

🤖 Generated with Claude Code

https://claude.ai/code/session_01Lbd6nqWmg4snvvBmegwqiw

@github-actions

Copy link
Copy Markdown

Overall Assessment

✅ Looks good. No unmitigated P0/P1 findings.

Executive Summary

  • No estimator, math, weighting, variance/SE, assumptions, or defaults changed.
  • ruff/black pins in .github/workflows/lint.yml match pyproject.toml.
  • The new Lint Gate job correctly uses if: always() and checks upstream job results.
  • Actions are SHA-pinned and workflow permissions are read-only.
  • Only minor optional test hardening noted.

Methodology

No findings. Affected methods: none. The diff is limited to CI, blame-ignore metadata, changelog, and contributor docs; docs/methodology/REGISTRY.md does not need a methodology update.

Code Quality

No findings.

Performance

No findings. The new workflow runs cheap static checks only.

Maintainability

No findings. The stable Lint Gate check name and documented pin-sync contract are clear.

Tech Debt

No findings. No new deferred methodology or correctness debt is introduced.

Security

No findings. .github/workflows/lint.yml:L24-L25 uses read-only contents permission, and the actions are SHA-pinned at .github/workflows/lint.yml:L36-L40.

Documentation/Tests

  • Severity: P3 informational
  • Impact: The workflow duplicates ruff/black versions from pyproject.toml; future drift could make local dev results differ from CI.
  • Concrete fix: Optional: add a lightweight test that reads .github/workflows/lint.yml:L41-L46 and pyproject.toml:L63-L69 and asserts the pinned ruff/black versions stay synchronized. This is not blocking because the PR documents the sync contract in CONTRIBUTING.md and CLAUDE.md.

@github-actions

Copy link
Copy Markdown

🔁 AI review rerun (requested by @igerber)

Head SHA: 1202c2bd0c8a08bf465f20d6fd9c708fcc46be9b


Overall Assessment

✅ Looks good. No unmitigated P0/P1 findings.

Executive Summary

  • No estimator, math, weighting, variance/SE, identification, or default behavior changed.
  • Affected methods: none; no methodology registry update is required.
  • The prior P3 pin-sync concern is addressed by a new test.
  • The lint workflow is check-only, uses read-only permissions, and SHA-pinned actions.
  • Remaining notes are P3 documentation/test-hardening items only.

Methodology

No findings. The diff does not touch diff_diff/, estimator logic, inference, assumptions, or docs/methodology/REGISTRY.md.

Code Quality

No findings.

Performance

No findings. The new CI job runs cheap static checks only.

Maintainability

No blocking findings.

Tech Debt

No findings. No new deferred methodology or correctness debt is introduced.

Security

No findings. .github/workflows/lint.yml:L24-L25 uses contents: read, and action usages are pinned by full SHA at .github/workflows/lint.yml:L36-L38.

Documentation/Tests

  • Severity: P3 informational
    Impact: The new pin-sync test at tests/test_openai_review.py:L4645-L4684 catches ruff/black drift when the broader test suite runs, but a future PR that edits only .github/workflows/lint.yml would not trigger rust-test.yml, whose workflow path filters currently omit lint.yml at .github/workflows/rust-test.yml:L36-L54. That leaves one drift direction unguarded.
    Concrete fix: Add .github/workflows/lint.yml to both push.paths and pull_request.paths in rust-test.yml, and extend the existing workflow-path-filter guard accordingly; alternatively, add a pin-compare step directly inside lint.yml.

  • Severity: P3 informational
    Impact: CONTRIBUTING.md:L13-L17 and CLAUDE.md:L34-L38 say lint/format/type pins are mirrored in .github/workflows/lint.yml, but lint.yml:L41-L46 currently installs/checks only ruff and black; mypy is pinned only in pyproject.toml:L63-L69.
    Concrete fix: Reword the docs to say the current Lint workflow mirrors ruff/black, with mypy pinned in pyproject.toml until the type-check job lands.

Validation note: I attempted the focused pin-sync test, but pytest is not installed in this review environment.

@github-actions

Copy link
Copy Markdown

🔁 AI review rerun (requested by @igerber)

Head SHA: b362ce572e15d7f39b37104df6538b94f2f60ade


Overall Assessment

✅ Looks good. No unmitigated P0/P1 findings.

Executive Summary

  • No estimator, math, weighting, variance/SE, identification assumption, or default behavior changed.
  • Affected methods: none; no methodology registry update is required.
  • Prior P3 path-filter concern is addressed: .github/workflows/lint.yml is now covered by both push.paths and pull_request.paths in .github/workflows/rust-test.yml:L24-L27 and L56-L59.
  • Prior P3 docs wording concern is addressed: docs now distinguish current ruff/black workflow mirroring from future mypy CI in CONTRIBUTING.md:L13-L20 and CLAUDE.md:L34-L39.
  • New lint workflow is check-only, ungated, read-only, and uses the repo’s SHA-pinned Actions pattern at .github/workflows/lint.yml:L24-L46.

Methodology

No findings. The PR does not touch diff_diff/, estimator behavior, inference, variance/SE, assumptions, or docs/methodology/REGISTRY.md. The methodology registry remains the estimator contract reference, and no affected method requires paper cross-checking for this CI/docs-only diff.

Code Quality

No findings. The Lint Gate aggregate job uses if: always() and explicitly fails on non-success upstream results, preserving the intended required-check semantics at .github/workflows/lint.yml:L53-L66.

Performance

No findings. The new workflow runs cheap static checks only: ruff check diff_diff tests and black --check diff_diff tests.

Maintainability

No findings. The pin-sync contract is now executable via TestLintWorkflowPinSync at tests/test_openai_review.py:L4668-L4707, and lint.yml edits now trigger the suite that owns that guard via tests/test_openai_review.py:L2206-L2227.

Tech Debt

No findings. No new deferred correctness, methodology, or inference debt is introduced.

Security

No findings. The workflow has top-level contents: read permissions and uses SHA-pinned actions/checkout / actions/setup-python at .github/workflows/lint.yml:L24-L38.

Documentation/Tests

No findings. The changelog and contributor docs accurately describe the current lint workflow and blame-ignore setup.

Validation note: I attempted to run the focused pytest guards, but this review environment does not have pytest installed (/usr/bin/python: No module named pytest). Static inspection confirmed the prior review items are addressed.

@igerber igerber added ready-for-ci Triggers CI test workflows and removed ready-for-ci Triggers CI test workflows labels Jul 12, 2026
…docs

- .github/workflows/lint.yml: runs `ruff check` + `black --check` at the
  pyproject-pinned versions on every PR push and on pushes to main. No
  ready-for-ci gate (precedent: ai_pr_review.yml), no paths filter (a
  required check whose workflow never triggers would block PRs forever).
  Aggregate "Lint Gate" job (if: always(), inspects needs.*.result) gives
  branch protection a single stable required-check name. Check-only.
- .git-blame-ignore-revs: the #677/#679 normalization squash SHAs.
- CONTRIBUTING.md "Linting and Formatting" section + CLAUDE.md note.
- TestLintWorkflowPinSync: executable ruff/black pin-sync guard between
  lint.yml and the pyproject dev extra (review round-2 P3).
- lint.yml added to rust-test.yml push/pull_request path filters, locked
  by PIN_SYNC_WORKFLOWS assertions; docs distinguish the current
  ruff/black mirroring from the future mypy CI job (round-3 P3s).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lbd6nqWmg4snvvBmegwqiw
@igerber igerber force-pushed the ci/lint-workflow branch from b362ce5 to 06ae0f6 Compare July 12, 2026 19:21
@github-actions

Copy link
Copy Markdown

🔁 AI review rerun (requested by @igerber)

Head SHA: 06ae0f62a0e82f1aa359c641d859ab4722f2c0de


Overall Assessment

✅ Looks good. No unmitigated P0/P1 findings.

Executive Summary

  • No diff_diff/ estimator, math, weighting, variance/SE, identification, or default behavior changes are introduced.
  • Prior re-review items appear resolved: .github/workflows/lint.yml is included in both rust-test path filters at .github/workflows/rust-test.yml:L24-L27 and .github/workflows/rust-test.yml:L56-L59.
  • The lint workflow is check-only, ungated, read-only, and uses SHA-pinned Actions at .github/workflows/lint.yml:L18-L46.
  • The aggregate Lint Gate runs with if: always() and fails on any non-success upstream result at .github/workflows/lint.yml:L53-L66.
  • Pin-sync coverage is now executable via TestLintWorkflowPinSync at tests/test_openai_review.py:L4668-L4707.

Methodology

No findings. Affected methods: none. This PR changes CI, blame-ignore metadata, docs, changelog, and review-workflow tests only; no estimator or methodology registry cross-check is required.

Code Quality

No findings. The workflow structure is straightforward and keeps a stable required-check job name while preserving failure propagation.

Performance

No findings. The added workflow runs only ruff check diff_diff tests and black --check diff_diff tests.

Maintainability

No findings. The new path-filter tests and pin-sync guard cover the main drift risks introduced by this CI workflow.

Tech Debt

No findings. No new deferred correctness or methodology debt is introduced.

Security

No findings. The workflow has permissions: contents: read and uses SHA-pinned third-party Actions.

Documentation/Tests

No findings. Contributor docs and CLAUDE.md describe the current ruff/black workflow and distinguish future mypy CI accurately.

Validation note: I attempted the focused pytest run, but this environment lacks pytest (/usr/bin/python: No module named pytest). Static inspection confirmed the relevant guards and pin values.

@igerber igerber added the ready-for-ci Triggers CI test workflows label Jul 12, 2026
@igerber igerber merged commit 37914ea into main Jul 12, 2026
27 of 28 checks passed
@igerber igerber deleted the ci/lint-workflow branch July 12, 2026 20:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ready-for-ci Triggers CI test workflows

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant