Process
API Council · Promotion checklist
The structured checklist every endpoint walks before it promotes Preview → Beta → GA. Each row is a load-bearing artefact reviewers verify; no exceptions without documented Council approval.
Last updated
Promotion checklist
Every endpoint walks this checklist before promotion. The structure mirrors the four-audit gate (Design / Security / Architecture / Testing) plus operational readiness. Each row carries:
- A documented artefact (file path, dashboard panel, runbook section).
- A reviewer (named).
- Sign-off (date + reviewer signature in PR).
Preview → Beta
| Lens | Item | Artefact | Reviewer |
|---|---|---|---|
| Design | OpenAPI spec PR reviewed | apps/docs/api-reference/openapi.yaml | API Council |
| Design | Field-level explainers on non-trivial props | x-matter-explainer blocks | Docs Editor |
| Design | Error codes have docs pages | apps/docs/content/docs/errors/<code>.mdx | Docs Editor |
| Design | Lifecycle annotation (x-matter-lifecycle.primary) | spec | API Council |
| Design | Voice rule respected — no competitor comparisons | grep audit | Anyone on Council |
| Security | Threat model row for any new attack surface | apps/docs/content/docs/security/threat-model.mdx | Security Owner |
| Security | Tenant-isolation red-team scenario added | apps/api/__tests__/tenant-isolation/ | Security Owner |
| Security | If HR fields involved: audit-on-read wired | apps/api/lib/middleware/audit-on-read-wrap.ts | Security Owner |
| Architecture | Adopts canonical 26-step pipeline | apps/api/lib/reference-handler.ts (per-handler profile) | Architecture Owner |
| Architecture | Service layer is pure (architecture test passes) | apps/api/__contracts__/architecture/services-are-pure.test.ts | Architecture Owner |
| Architecture | If composite: TLA+ spec for compensation | packages/<service>/<service>.tla | Architecture Owner |
| Testing | Unit + integration + property tests | apps/api/__tests__/<resource>*.test.ts | Testing Owner |
| Testing | Mock-vs-real parity row | apps/api/__tests__/mock-parity.test.ts PARITY_FIXTURES | Testing Owner |
| Testing | Cost-budget asserted under load | apps/api/lib/cost-budgets.ts + load test | Operations |
| Operations | Runbook for known failure modes | apps/docs/content/docs/runbooks/<operation>.mdx | On-call |
| Operations | Per-operation SLO budget published | apps/api/SLOs.md | Operations |
Beta → GA
| Lens | Item | Artefact | Reviewer |
|---|---|---|---|
| Design | Customer feedback synthesised | Council PR body | API Council |
| Design | Migration guide if replacing an endpoint | apps/docs/content/docs/migrations/<op>.mdx | Docs Editor |
| Security | Pentest finding (if any) resolved | apps/docs/content/docs/security/pentest-findings/ | Security Owner |
| Security | Audit-chain coverage drift = 0 | apps/api/__contracts__/audit-coverage-drift.test.ts | Security Owner |
| Architecture | Cross-version compat tests pass against the previous minor | apps/api/__tests__/cross-version.test.ts | Architecture Owner |
| Architecture | Cache layer declared if read-heavy | packages/cache/src/index.ts CACHE_LAYERS | Architecture Owner |
| Testing | Property + clock-skew + i18n + mutation score ≥ 80 | reports | Testing Owner |
| Testing | SDK conformance suite passes per SDK | packages/sdk-conformance | Testing Owner |
| Operations | SLOs met under baseline load in all three modes | k6 measurements | Operations |
| Operations | Cost-per-request budget verified | apps/api/lib/cost-budgets.ts + measured | Operations |
| Operations | Quota tier limits set | apps/api/lib/quota-snapshot.ts | Operations |
| Operations | Status page tile + alert routing wired | tooling/status-probes/ + apps/api/RUNBOOK.md | Operations |
| Customer surfaces | CLI command implemented | packages/cli/ | DX Owner |
| Customer surfaces | Cookbook recipe published | apps/docs/content/docs/cookbook/<recipe>.mdx | Docs Editor |
| Customer surfaces | In-browser console form exists | apps/app/(authenticated)/developers/console/ | DX Owner |
GA → Deprecated (sunsetting)
| Item | Artefact | Reviewer |
|---|---|---|
| Migration guide for the replacement | apps/docs/content/docs/migrations/<op>.mdx | Docs Editor |
| Per-customer personalised notice | apps/api/app/cron/personalised-deprecation-emails/ | Operations |
Deprecation + Sunset headers emit automatically | apps/api/lib/maturity-gate.ts | Architecture Owner |
| Minimum 90-day deprecation notice | calendar | API Council |
| Minimum 24-month sunset window | calendar | API Council |
Migration tooling: matter migrate-deprecated updated | packages/cli/ | DX Owner |
| Per-endpoint usage telemetry tracked | dashboard | Operations |
Sign-off process
- Author opens a promotion PR with the maturity transition + the completed checklist (file paths in the PR body).
- Reviewers tick rows as they verify. Outstanding rows block merge.
- The API Council weekly forum reviews any non-trivial transitions synchronously; trivial Preview → Beta moves are async.
- Once every row carries a reviewer signature, the spec PR merges +
the
x-matter-maturityannotation flips. - Telemetry begins tracking the new stage's adoption from merge time.