Carlos Florêncio
126 lines
4.1 KiB
Markdown
126 lines
4.1 KiB
Markdown
---
|
|
id: "02-consolidate-documentation-api-reads"
|
|
title: "Consolidate documentation API reads"
|
|
status: done
|
|
wave: 2
|
|
depends_on:
|
|
- "01-rate-aware-api-recovery"
|
|
plan: "plan.md"
|
|
requirements:
|
|
- REQ-CI-PR-DOCS-002
|
|
- REQ-CI-PR-DOCS-003
|
|
- REQ-CI-PR-DOCS-004
|
|
acceptance_criteria:
|
|
- AC-CI-PR-DOCS-002.2
|
|
- AC-CI-PR-DOCS-003.1
|
|
- AC-CI-PR-DOCS-003.2
|
|
- AC-CI-PR-DOCS-004.1
|
|
- AC-CI-PR-DOCS-004.2
|
|
- AC-CI-PR-DOCS-004.3
|
|
- AC-CI-PR-DOCS-004.4
|
|
system_design:
|
|
- ../../specs/ci/system-design/pull-request-documentation-coverage.md
|
|
---
|
|
|
|
# Task 02: Consolidate documentation API reads
|
|
|
|
## Summary
|
|
|
|
Reuse exact-head and base data, remove a duplicate pull request read, and avoid
|
|
full evaluations for events that cannot change documentation coverage.
|
|
|
|
## In scope
|
|
|
|
- `.github/scripts/pr-docs.cjs`
|
|
- `.github/scripts/pr-docs.test.cjs`
|
|
- `.github/workflows/pr-docs.yml`
|
|
- `.github/scripts/pr-docs-workflow-contract_test.py`
|
|
- This work order's implementation results
|
|
|
|
## Out of scope
|
|
|
|
Coverage-policy exemptions, artifact frontmatter, merge-group membership,
|
|
rulesets, tokens, and other GitHub workflows.
|
|
|
|
## Acceptance
|
|
|
|
- Reuse the pending-status pull request snapshot. Perform one later consistency
|
|
read for a stable pull request. Read each `(revision, path)` once.
|
|
- Resolve a verified existing requirement from changed head/base documents with
|
|
zero code-search calls. Keep bounded fallback and duplicate detection for new,
|
|
moved, missing, or ambiguous IDs.
|
|
- Route opened, reopened, synchronize, base-branch retargets, exact
|
|
`no-docs-allow` label transitions, dispatch, and merge-group checks. Skip
|
|
title, description, readiness, and unrelated label events before checkout or
|
|
API use.
|
|
|
|
## 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/pr-docs.yml
|
|
git diff --check
|
|
```
|
|
|
|
## Files likely touched
|
|
|
|
- `.github/scripts/pr-docs.cjs`
|
|
- `.github/scripts/pr-docs.test.cjs`
|
|
- `.github/workflows/pr-docs.yml`
|
|
- `.github/scripts/pr-docs-workflow-contract_test.py`
|
|
- `docs/plans/github-api-resilience/task-02-consolidate-documentation-api-reads.md`
|
|
|
|
## Dependencies
|
|
|
|
Task 01.
|
|
|
|
## Risks
|
|
|
|
Start a fresh cache after metadata instability and for every merge-group member.
|
|
Scan all changed requirement documents in a referenced directory before relying
|
|
on trusted-base uniqueness.
|
|
|
|
## 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)
|
|
- `.github/AGENTS.md`
|
|
|
|
## Results
|
|
|
|
Implemented the exact-revision read strategy in `.github/scripts/pr-docs.cjs`
|
|
and the relevant event gates in `.github/workflows/pr-docs.yml`.
|
|
|
|
- The initial pull request snapshot used for the pending status is passed into
|
|
evaluation, leaving one later consistency read for a stable run.
|
|
- Content reads use a `(revision, path)` cache. Changed requirement documents
|
|
are loaded at the exact head before search, and their corresponding base
|
|
paths are loaded once for identity comparison.
|
|
- Existing or renamed requirement definitions with the same requirement
|
|
heading/ID in their trusted base path skip code search, including body or
|
|
acceptance-text changes. New, moved without a trusted base identity, missing,
|
|
and ambiguous identities keep the bounded search and directory fallback.
|
|
- The workflow admits only opened, reopened, synchronize, base-branch retargets,
|
|
exact override-label transitions, manual dispatch, and merge-group checks.
|
|
Title and description edits, readiness changes, and unrelated label events
|
|
are rejected at the job gate.
|
|
|
|
Verification:
|
|
|
|
- `node --test .github/scripts/pr-docs.test.cjs` (75 passed)
|
|
- `python3 .github/scripts/pr-docs-workflow-contract_test.py` (7 passed)
|
|
- `python3 .github/scripts/lint-action-pinning_test.py` (9 passed)
|
|
- `python3 .github/scripts/lint-action-pinning.py` (24 workflows passed)
|
|
- `zizmor .github/workflows/pr-docs.yml` (no findings)
|
|
- `git diff --check` (passed)
|