## Summary Splits the lint workflow into jobs so that a red run identifies which lint stage broke, and so link checking no longer blocks or delays the rest of the documentation linting. | Job | Target | Runs when | |---|---|---| | `filter` | none | always; classifies the changed files | | `files` | `make -k lint-code` | source files changed | | `docs` | `make -k docs-lint` | documentation changed | | `linkcheck` | `make -k docs-linkcheck` | documentation changed | Draft: the workflow shape is settled, but nothing has run against a real runner yet. ## Related starbase change The starbase side of this split is canonical/starbase#625, which adds an explicit `docs-linkcheck` target. Its `docs-%` passthrough routes `docs-linkcheck` the same way, so this workflow works either way, but #625 makes the target explicit and keeps `make lint` running link checking. Merge order matters. Both orders are being tested: - canonical/starbase#626, starbase's change plus this workflow, for starbase merged first. - canonical/starbase#627, this workflow without starbase's change, for starflow merged first. The `linkcheck` job is expected to fail there. ## Changes **Makefile** - Renamed the `lint` target to `lint-code`. - Removed `linkcheck` from `docs-lint`. No new target was added: the existing `docs-%` passthrough already routes `docs-linkcheck` to `make -C docs linkcheck`. **lint-python.yaml** - Added a `filter` job that runs `dorny/paths-filter` once and exports `source-files` and `docs-files` as job outputs. The three linting jobs take `needs: filter` and gate at job level. - Added a `docs-files` filter covering `docs/**`, `**/*.md`, `**/*.rst`, and `.readthedocs.yaml`. - The `docs` and `linkcheck` jobs keep only the `setup-uv` step, since neither the documentation linters nor Sphinx's linkchecker need the snap-installed linters. - `pull-requests: read` now exists only on `filter`, which is the only job that calls the pull request API. **README** - Documents the three jobs, the renamed `lint-code` target, the previously undocumented `docs-lint` and `docs-linkcheck` targets, and the `source-files` input. ## Review responses All four Copilot findings and the zizmor alert were addressed: - Truncated `setup-uv` SHA (2c77769). - Documentation filters omitting `.readthedocs.yaml` (46f37bc). - Step-level instead of job-level gating (46f37bc). - Renaming `lint` against the documented contract (46f37bc). This one is a deliberate breaking change for consumers, discussed below. ## Behaviour changes worth reviewing **The `source-files` input only exists for `workflow_call`.** On `push` and `pull_request` events it is empty, so the old condition `inputs.source-files == 'true'` never matched and self-linting runs of this repository only ever executed the documentation linters. The `files` job now uses `inputs.source-files != 'false'`, so an unset input counts as "not docs-only" and the code linters run on pushes and pull requests to `main`. Callers that pass `source-files: 'false'` still skip them. **Mixed changes now run both code and documentation linting.** A pull request touching source files and documentation runs all three linting jobs, where the previous exclusive either/or would have run only the code linters. Gating both documentation jobs on a single shared filter also means a pull request that changes only source files no longer starts a runner for `docs` and `linkcheck`, which previously checked out the repository and installed `uv` before the final step's condition was evaluated. **Consumers must rename `lint` to `lint-code`.** Any repository calling this workflow needs the renamed target. An alias in this repository's Makefile would not help, since callers supply their own. If a non-breaking change is preferred, the alternative is to keep invoking `lint` and drop the rename. ## Testing - `make -n lint-code`, `make -n docs-lint`, and `make -n docs-linkcheck` all resolve to the expected recipes. - `prettier --check` passes over the repository glob. - Every `uses:` reference in the workflow is pinned to a 40-character commit SHA. - Workflow YAML parses, and the job graph and conditions were inspected directly. Not yet verified against a real runner.