Carlos Florêncio
116 lines
3.7 KiB
Markdown
116 lines
3.7 KiB
Markdown
---
|
|
id: "03-queue-coverage"
|
|
title: "Support merge queue coverage"
|
|
status: done
|
|
wave: 3
|
|
depends_on:
|
|
- "02-pr-workflow"
|
|
plan: "plan.md"
|
|
requirements:
|
|
- REQ-CI-PR-DOCS-001
|
|
- REQ-CI-PR-DOCS-002
|
|
- REQ-CI-PR-DOCS-003
|
|
acceptance_criteria:
|
|
- AC-CI-PR-DOCS-001.6
|
|
- AC-CI-PR-DOCS-002.2
|
|
- AC-CI-PR-DOCS-003.1
|
|
- AC-CI-PR-DOCS-003.4
|
|
- AC-CI-PR-DOCS-003.5
|
|
system_design:
|
|
- ../../specs/ci/system-design/pull-request-documentation-coverage.md
|
|
---
|
|
|
|
# Task 03: Support merge queue coverage
|
|
|
|
## Summary
|
|
|
|
Add merge-group membership resolution and per-member evaluation. Reconcile live group status after label changes. Document contribution examples, exact exemptions, label persistence, structural limits, dispatch retries, and administrator rollout.
|
|
|
|
## In scope
|
|
|
|
- `.github/workflows/pr-docs.yml`
|
|
- `.github/scripts/pr-docs.cjs`
|
|
- `.github/scripts/pr-docs.test.cjs`
|
|
- `.github/scripts/pr-docs-workflow-contract_test.py`
|
|
- `.github/pull_request_template.md`
|
|
- `.github/AGENTS.md`
|
|
- `CONTRIBUTING.md`
|
|
- `docs/ci-merge-queue.md`
|
|
|
|
## Out of scope
|
|
|
|
Application code, unrelated workflow cleanup, live label changes, and live ruleset changes.
|
|
|
|
## Acceptance
|
|
|
|
- Queue groups evaluate every member independently and publish the same context on the group head; missing or ambiguous membership fails.
|
|
- Removing an override reevaluates affected current groups without reusing an obsolete success.
|
|
- Contributor instructions and rollout checks distinguish deployed failures from ruleset-enforced blocking, with no live ruleset edits.
|
|
|
|
## Verification
|
|
|
|
Run from the repository root:
|
|
|
|
```bash
|
|
node --test .github/scripts/pr-docs.test.cjs
|
|
python3 .github/scripts/pr-docs-workflow-contract_test.py
|
|
python3 .github/scripts/lint-action-pinning_test.py
|
|
python3 .github/scripts/lint-action-pinning.py
|
|
zizmor .github/workflows
|
|
python3 scripts/lint-spec-files.py --all
|
|
git diff --check
|
|
```
|
|
|
|
## Files likely touched
|
|
|
|
- `.github/workflows/pr-docs.yml`
|
|
- `.github/scripts/pr-docs.cjs`
|
|
- `.github/scripts/pr-docs.test.cjs`
|
|
- `.github/scripts/pr-docs-workflow-contract_test.py`
|
|
- `.github/pull_request_template.md`
|
|
- `.github/AGENTS.md`
|
|
- `CONTRIBUTING.md`
|
|
- `docs/ci-merge-queue.md`
|
|
|
|
## Dependencies
|
|
|
|
Task 02.
|
|
|
|
## Risks
|
|
|
|
Queue head/base mapping is a GitHub integration assumption. Validate with captured real payloads before adding the required context; do not pass unknown groups.
|
|
|
|
## Parallelism
|
|
|
|
`sequential`
|
|
|
|
## Inputs
|
|
|
|
- [Requirements](../../specs/ci/requirements/pull-request-documentation-coverage.md)
|
|
- [System design](../../specs/ci/system-design/pull-request-documentation-coverage.md)
|
|
- [Plan](plan.md)
|
|
- [Decision](../../decisions/2026-09-10-pr-documentation-coverage.md)
|
|
- `.github/AGENTS.md` and existing PR size workflow contract tests.
|
|
|
|
## Results
|
|
|
|
Implemented exact merge-group boundary resolution, independent member
|
|
evaluation, all active prefix reevaluation after label removal, target-branch
|
|
serialization with a bounded pending queue, contributor guidance, and the
|
|
administrator rollout notes. The workflow publishes the shared status on the
|
|
synthetic group head without changing labels, queue membership, or rulesets.
|
|
|
|
Verification:
|
|
|
|
- `node --test .github/scripts/pr-docs.test.cjs`: 35 tests passed.
|
|
- `python3 .github/scripts/pr-docs-workflow-contract_test.py`: 5 tests passed.
|
|
- `python3 .github/scripts/lint-action-pinning_test.py`: 9 tests passed.
|
|
- `python3 .github/scripts/lint-action-pinning.py`: 24 workflows passed.
|
|
- `python3 scripts/lint-spec-files.py --all`: passed.
|
|
- `zizmor .github/workflows/pr-docs.yml`: no findings.
|
|
- `git diff --check`: passed.
|
|
|
|
The repository-wide `zizmor .github/workflows` command still reports existing
|
|
findings in unrelated workflows. Live merge-group payload validation remains a
|
|
deployment step before the status becomes required.
|