docs(research): 0061 docs-only PR CI fast-track design#393
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
This PR adds a research/design document and changelog entry for speeding up docs-only pull requests by avoiding the full required CI matrix while preserving GitHub required-check behavior.
Changes:
- Add a research note describing the proposed detector/shim pattern for docs-only CI fast-tracking.
- Document the current required-check inventory, proposed rollout phases, and risks.
- Add a changelog entry summarizing the design proposal and its intended scope.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| docs/research/0061-docs-only-ci-fast-track.md | New research document describing the proposed docs-only CI fast-track design, rollout plan, and risks. |
| changelog.d/added/research-0061-docs-only-ci-fast-track.md | New changelog fragment summarizing the research/design proposal. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | approach | failure mode | | ||
| |----------|--------------| | ||
| | Add `paths-ignore: ['docs/**']` to heavy workflows | Required checks then never report → branch protection blocks merge indefinitely. Per GitHub: "If a required status check isn't reported, the pull request is blocked." | | ||
| | Job-level `if:` that skips on docs-only | GitHub reports the job as `skipped`, not `success`. Branch protection treats `skipped` as missing for required checks (verified empirically on this repo, recent PRs). | |
Comment on lines
+4
to
+10
| the working "shim + paths-filter detector" approach (the only one | ||
| that satisfies GitHub branch protection's "skipped is not success" | ||
| semantic), scopes it across the required-check inventory (18 of 23 | ||
| checks are skippable on docs-only diffs), and recommends a phased | ||
| rollout starting with `libvmaf-build-matrix.yml`. No code change in | ||
| this PR — design only; implementation deferred until the current | ||
| merge train drains. |
| | Sanitizers (ASan / UBSan / TSan) | 3 | yes | | ||
| | CodeQL (Actions / C/C++ / Python) | 3 | yes (for docs-only — no code to scan) | | ||
| | Pre-Commit (formatters) | 1 | NO — markdown lint runs here | | ||
| | Python Lint | 1 | NO — checks .py docstrings? actually yes if no .py touched | |
| - '!changelog.d/**' | ||
| - '!**/*.md' | ||
| - '!**/AGENTS.md' | ||
| ``` |
| detector.** If `dorny/paths-filter`'s `code:` predicate misses a | ||
| newly-added directory (e.g. a new top-level `tools_v2/`), the | ||
| heavy job is skipped for code that should have been built. Test | ||
| coverage: include a `'!docs/**'` + `'!changelog.d/**'` + `'!*.md'` |
| waits ~25 minutes for the full 23-required-check CI matrix. Documents | ||
| the working "shim + paths-filter detector" approach (the only one | ||
| that satisfies GitHub branch protection's "skipped is not success" | ||
| semantic), scopes it across the required-check inventory (18 of 23 |
This was referenced May 5, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Docs-only PRs currently wait ~25 min for the full 23-required-check CI matrix. This is design-only — proposes the shim + paths-filter pattern that's the standard fix and the only one that satisfies GitHub's required-check semantics.
Why straightforward fixes fail:
paths-ignoreon heavy workflows → required checks never report → PR blocked foreverif:skip → GitHub reportsskipped, branch protection treats it as missing → blockedWorking pattern: detector job + heavy job (gated on detector) + shim job with same
name:(= same required-check context). Shim runs <10s on docs-only diffs, reports success under the same context.Scope: ~18 of 23 required checks are skippable on docs-only PRs. Non-skippable: Pre-Commit (markdown lint), Gitleaks (token scan must run on docs too), Python Lint.
Recommends phased rollout: pilot on
libvmaf-build-matrix.yml(6 required check names), validate <5min docs-only cycle, then extend.ADR-0108 deliverables
docs/research/0061-docs-only-ci-fast-track.mdno alternatives: only-one-way fix — GitHub's required-check semantics rule out paths-ignore and
if:skipno rebase-sensitive invariants: design only, no code
no reproducer: pure design
changelog.d/added/research-0061-docs-only-ci-fast-track.mdno rebase impact: docs-only addition under
docs/research/🤖 Generated with Claude Code