[lengau]

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:

• ci: test starbase with starflow's split lint workflow starbase#626, starbase's change plus this workflow, for starbase
  merged first.
• ci: test starbase main with starflow's split lint workflow 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.

[Copilot]

🟡 Changes recommended

Critical workflow and compatibility issues remain unresolved.

4 open findings

• Truncated setup-uv commit SHA breaks linkcheck · New
• Renaming lint target breaks reusable workflow callers · New
• Docs filters omit .readthedocs.yaml · New
• Linkcheck job is not gated at the job level · New

What changed in this PR

Splits Python linting into independent code, documentation, and link-check workflow jobs.

Changes:

• Renames lint to lint-code and separates documentation link checking.
• Adds path-filtered docs and linkcheck jobs.
• Updates source-file gating for push, pull request, and reusable workflow runs.

File	Review findings
Makefile	Critical (4 votes): Renaming lint breaks the documented reusable-workflow contract; retain a compatibility alias or update/version the contract.
.github/​workflows/​lint-python.yaml	Critical (2 votes): The linkcheck setup reference uses a truncated SHA. Moderate: Job gating remains step-level, .readthedocs.yaml is omitted from documentation filters, and RST changes are not excluded from the source filter.

🧠 Review effort: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[mr-cal]

None of the example PRs made a doc change, so the linkchecker and doc workflows haven't been proven. Are you able to adjust it so we can see those run?

[lengau]

@mr-cal I believe canonical/starbase#632 is what you're looking for.

[lengau]

@mr-cal and here's one that skips the code linting but runs the docs/linkcheck: LoweRAM/charmcraft#1

[mr-cal]

Thanks for the runs, interesting failure on the linkchecker: https://github.com/LoweRAM/charmcraft/actions/runs/39987431539/job/120530361084?pr=1#step:4:339

[lengau]

Odd that it did that in that charmcraft one but not in craft-application. Looking...

[lengau]

@mr-cal ok I've added make setup-docs as a step for both the docs linters and for linkcheck: https://github.com/LoweRAM/charmcraft/actions/runs/40000066581/job/120573734845