ci(lint): improve CI UX when splitting linter jobs
Metadata
Current evaluation
⚠️ This summary may be outdated — the issue content or evaluation prompts have changed since this evaluation was made.
Splits linkcheck from docs-lint into a standalone docs-linkcheck Make target to enable separate CI lint jobs. All CI passing, awaiting first review.
Resolution: needs review
Reason: The PR is a small, well-documented Makefile change (+12/-1 lines) that splits linkcheck from docs-lint into a standalone target for better CI UX. All CI checks are passing, the author (a maintainer) provided a clear test plan and compatibility analysis with downstream PRs, and there is no review feedback to address. It is ready for maintainer review.
Evaluated by: mr-cal-bot
Impact:
35
Quick Win:
24
Complexity:
10
Confidence:
80
Actionability:
75
Issue body
## Problem
`canonical/starflow/.github/workflows/lint-python.yaml` runs all code and
documentation linters in a single job. Link checking is slow and hits the
network, so it slows down every job that depends on it.
To split linting into separate CI jobs, `linkcheck` needs to be a standalone
Make target rather than part of `docs-lint`.
## Changes
- Add a `docs-linkcheck` target that runs `make -C docs linkcheck`.
- Remove `linkcheck` from `docs-lint`, which keeps running `sphinx-lint`,
`spelling`, and `woke`.
- Add `docs-linkcheck` as a prerequisite of `lint`, so `make lint` and local
behaviour are unchanged.
Downstream repos get the new target automatically the next time they merge
from `starbase/main`.
## Compatibility testing
This PR is only the starbase half. The starflow half that consumes it is
canonical/starflow#199.
The merge order matters, so both orders are tested by these draft PRs:
- **Forwards compatible** — starbase merged first, starflow still on `main`:
canonical/starbase#626. Based on this branch, points the `lint` job at
starflow's `work/separate-linkcheck`.
- **Backwards compatible** — starflow merged first, starbase still on `main`:
canonical/starbase#627. Based on `main`, points the `lint` job at starflow's
`work/separate-linkcheck`. The `linkcheck` job is expected to fail, since
`docs-linkcheck` does not exist on `main`.
If #627 fails, starbase has to land before starflow.
Each of those two test PRs also has a docs-only PR stacked on top of it,
to check the filter classifies a documentation-only change correctly and
skips the code linters:
- canonical/starbase#628, stacked on #626.
- canonical/starbase#630, stacked on #627.
The same two stacks also each have a PR that changes a source file and a
documentation file together, to check that all three linting jobs run rather
than only one:
- canonical/starbase#632, stacked on #628.
- canonical/starbase#633, stacked on #630.
## Test plan
- `make format`, `make lint`, `make test-fast`
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| qwen/qwen3.6-35b-a3b |
Impact:
35
Quick Win:
24
Complexity:
10
Confidence:
80
Actionability:
75
|
needs review | Splits linkcheck from docs-lint into a standalone docs-linkcheck Make target to enable separate CI lint jobs. All CI passing, awaiting first review. | |
| qwen/qwen3.6-35b-a3b |
Impact:
45
Quick Win:
32
Complexity:
10
Confidence:
85
Actionability:
80
|
needs review | Adds a standalone docs-linkcheck Make target and removes linkcheck from docs-lint to enable splitting lint jobs in CI. All CI checks passing, awaiting maintainer review. | |
| qwen/qwen3.6-35b-a3b |
Impact:
35
Quick Win:
25
Complexity:
10
Confidence:
85
Actionability:
80
|
needs review | Adds docs-linkcheck Make target and splits linkcheck from docs-lint to improve CI UX. All CI checks passing, no review comments. |
Update history
| Date | Change |
|---|---|
| closed | |
| updated | |
| updated | |
| updated | |
| updated | |
| created |
Related work
-
Related To:
canonical/starflow#199
(confidence 90%)
The starflow half that consumes the new docs-linkcheck target, mentioned in the PR body as the downstream consumer.
-
Related To:
canonical/starbase#626
(confidence 85%)
Forwards compatibility test PR: starbase merged first, starflow still on main.
-
Related To:
canonical/starbase#627
(confidence 85%)
Backwards compatibility test PR: starflow merged first, starbase still on main.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #199 ci(lint-python): split linting into code, docs, and linkcheck jobs | starflow | merged | Merged PR splitting the lint workflow into filter, files, docs, and linkcheck jobs. Renames lint to lint-code and updates lint-python.yaml and Makefile to run stages in parallel based on changed files. | |
| #628 docs: add docs-linkcheck to the commands to test | starbase | closed | Test PR to validate CI path filtering for docs-only changes. Closed without merging after confirming the filter correctly skips lint-code and runs docs jobs. | |
| #508 fix: quieter docs-lint in CI | starbase | merged | Merged #508, grouping docs-lint setup and execution in CI log groups to reduce verbosity; all reported checks passed. |