Add .github/workflows/README.md that explains, in plain English (for a developer new to the repo), how the CI traffic-controller works as it currently stands — the traffic-control job in ci.yml (priority-based runner orchestration, ~L23–210).
Cover:
What it is for: GitHub Actions has no native priority queue, so this job orders PRs access to CI runners by a priority label.
Preemption:P0 preempts (cancels) the in-progress/queued runs of ALL strictly-lower-priority other PRs to reclaim runners; a broken PR run may be cancelled by any higher-priority PR; P1–P9 yield without bumping — they never cancel a non-broken lower-priority run, they just wait (bounded).
Safety invariants: never cancels a run on main/push, never cancels the PR own run, never cancels an equal-or-higher-priority run.
Honest limitation: the bounded-wait approach and why (no native priority queue).
Plain-English prose (a small table for the priority levels is fine). Note that #342 is refactoring this logic into a testable Python module with minor refinements (drafts also ⇒ P10; explicit same-level ordering: in-flight run continues, then oldest-waiting first) — so this README should be updated when #342 lands.
Small doc task; .github/workflows/README.md only.
Add `.github/workflows/README.md` that explains, in **plain English** (for a developer new to the repo), how the CI **traffic-controller** works **as it currently stands** — the `traffic-control` job in `ci.yml` (priority-based runner orchestration, ~L23–210).
Cover:
- **What it is for:** GitHub Actions has no native priority queue, so this job orders PRs access to CI runners by a priority label.
- **Effective priority:** lowest-numbered `P0`–`P9` label (P0 = highest / emergency-only), default `P5` if none; the `broken` label ⇒ 10 (bottom, below P9).
- **Preemption:** `P0` preempts (cancels) the in-progress/queued runs of ALL strictly-lower-priority *other* PRs to reclaim runners; a `broken` PR run may be cancelled by any higher-priority PR; `P1`–`P9` yield without bumping — they never cancel a non-broken lower-priority run, they just wait (bounded).
- **Safety invariants:** never cancels a run on `main`/push, never cancels the PR own run, never cancels an equal-or-higher-priority run.
- **Honest limitation:** the bounded-wait approach and why (no native priority queue).
Plain-English prose (a small table for the priority levels is fine). Note that **#342** is refactoring this logic into a testable Python module with minor refinements (drafts also ⇒ P10; explicit same-level ordering: in-flight run continues, then oldest-waiting first) — so this README should be updated when #342 lands.
Small doc task; `.github/workflows/README.md` only.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Add
.github/workflows/README.mdthat explains, in plain English (for a developer new to the repo), how the CI traffic-controller works as it currently stands — thetraffic-controljob inci.yml(priority-based runner orchestration, ~L23–210).Cover:
P0–P9label (P0 = highest / emergency-only), defaultP5if none; thebrokenlabel ⇒ 10 (bottom, below P9).P0preempts (cancels) the in-progress/queued runs of ALL strictly-lower-priority other PRs to reclaim runners; abrokenPR run may be cancelled by any higher-priority PR;P1–P9yield without bumping — they never cancel a non-broken lower-priority run, they just wait (bounded).main/push, never cancels the PR own run, never cancels an equal-or-higher-priority run.Plain-English prose (a small table for the priority levels is fine). Note that #342 is refactoring this logic into a testable Python module with minor refinements (drafts also ⇒ P10; explicit same-level ordering: in-flight run continues, then oldest-waiting first) — so this README should be updated when #342 lands.
Small doc task;
.github/workflows/README.mdonly.