ci: scope-aware build matrix

[alandefreitas]

Cuts CI time on PRs that don't touch the build inputs, and splits the monolithic ci-releases.yml so docs work is scope-gated and publication runs once.

A new scope-detector reusable workflow classifies the changed files into the same scope buckets Danger uses (util/danger/logic.ts) and probes the develop-release GitHub Release plus the coverage-develop artifact for warmth. It derives a matrix-selector value (full, releases-and-coverage, releases, coverage, or none) that ci.yml uses to dispatch ci-build.yml into the right cpp-matrix submatrix. Pushes to develop/master/tags, a [full ci] body marker, and a full-ci label all force the full matrix.

When both caches are warm and no code-affecting file changed, ci-build is skipped entirely. The per-OS Release and Documentation jobs then pull packages from develop-release instead of from a fresh build, so the required status checks still reflect a real install and run of the binary.

Changes

• Source: none.
• Tests: 13 new vitest cases for codeChangeScopes, scopesTouched(), and isCodeChange() (51 total).
• CI:
  • New ci-scope-detector.yml reusable workflow with twelve outputs: is-code-change, is-docs-change, is-push, force-full, release-cache-warm, coverage-cache-warm, run-full-matrix, run-release-build, run-coverage-build, run-documentation, matrix-selector, merge-base-sha, scopes-json.
  • ci-matrix.yml adds coverage and releases-and-coverage submatrices alongside the existing releases.
  • ci.yml wires the detector, dispatches build into the selected (sub)matrix, and adds the new per-OS Release / Documentation jobs plus a single Publish job. The release and documentation jobs use if: always() so a skipped build doesn't block them on no-code PRs.
  • ci-build.yml uploads the produced LCOV as a coverage-develop artifact (90-day retention) on develop pushes only. The strict coverage probe checks for this artifact by name and merge-base SHA.
  • ci-utility-tests.yml replays that LCOV to codecov on PRs that skipped the Coverage matrix entry, tagged with the PR's commit SHA, so codecov/patch and codecov/project post statuses without rebuilding.
  • Splits the old ci-releases.yml into three workflows:
    • ci-release.yml: per-OS smoke and third-party demo generation. Always required.
    • ci-documentation.yml: per-OS docs, website, and Antora UI render. Scope-gated on source, docs, build, and third-party.
    • ci-publish.yml: single Linux runner, push to develop/master/tags only. Renders the multi-ref Antora site, publishes to GitHub Pages and the dev-websites rsync target, and creates one consolidated GitHub Release with all three platform packages.
  • ci-release.yml and ci-documentation.yml accept a use-develop-binaries input that switches the package source from actions/download-artifact to gh release download develop-release.
• Tooling: new util/danger/detect-scopes.ts CLI (stdin to JSON) and npm run danger:detect-scopes script.

Testing

• npm --prefix util/danger test passes 51/51 locally.
• All eight touched workflow files parse cleanly as YAML.
• CLI smoke check: src/lib/foo.cpp + docs/index.adoc returns is_code_change: true; docs/index.adoc + README.adoc returns is_code_change: false.
• End-to-end flow needs the first develop push to land before the coverage-develop artifact exists. Until then every PR is coverage-cold and rebuilds the Coverage entry for real, which is the documented fallback.
• The strict coverage probe filters by workflow_run.head_sha == merge_base(PR, develop), so a PR built on a develop SHA that's behind the latest pushed develop falls back to a fresh Coverage build.

Branch protection

Required status check names change with the split:

• Old: Releases / Linux, Releases / Windows, Releases / macOS (plural, from the old monolithic workflow).
• New: Release / Linux, Release / Windows, Release / macOS (singular, from ci-release.yml).

The codecov/patch and codecov/project checks are unchanged.

Documentation

No user-facing changes; this PR only touches CI. The util/danger/README.md already documents the scope buckets the detector reuses. The util/danger/detect-scopes.ts script header explains the stdin/JSON contract for anyone wiring it up elsewhere.

[github-actions]

🧾 Changes by Scope

Scope	Lines Δ%	Lines Δ	Lines +	Lines -	Files Δ	Files +	Files ~	Files ↔	Files -
⚙️ CI	100%	1613	1375	238	15	4	11	-	-
Total	100%	1613	1375	238	15	4	11	-	-

Legend: Files + (added), Files ~ (modified), Files ↔ (renamed), Files - (removed)

🔝 Top Files

• .github/workflows/ci-scope-detector.yml (CI): 281 lines Δ (+281 / -0)
• util/danger/logic.test.ts (CI): 278 lines Δ (+278 / -0)
• .github/workflows/ci-publish.yml (CI): 263 lines Δ (+263 / -0)

Generated by 🚫 dangerJS against 1b1be96

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.12%. Comparing base (18818c9) to head (1b1be96).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #1206   +/-   ##
========================================
  Coverage    82.12%   82.12%           
========================================
  Files           33       33           
  Lines         3149     3149           
  Branches       734      734           
========================================
  Hits          2586     2586           
  Misses         387      387           
  Partials       176      176           

Flag	Coverage Δ
bootstrap	82.12% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6af4ad2d2e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[cppalliance-bot]

An automated preview of the documentation is available at https://1206.mrdocs.prtest2.cppalliance.org/index.html

If more commits are pushed to the pull request, the docs will rebuild at the same URL.

2026-05-16 05:38:43 UTC