ADR 0018: ADR lifecycle, status model, and ratification

Ratification

This ADR defines the standard lifecycle for ADRs in this repo. When ratification is done, add the discussion Issue (use the ADR template; title starts with [ADR]), the merge PR, and the acceptance date here.

• Discussion Issue: see repository issues
• Merge PR: see git history for this file
• Accepted: 2026-04-12

Context

Why this matters: Readers must see whether an ADR is still a draft, accepted, or done. One small machine-readable field on each page keeps the site accurate without a separate “ADR status” spreadsheet.

ADRs are static HTML under docs/adr/. We use one lifecycle: what we decided, how we ratified it (Issue + PR), and how far documentation and code have progressed — without a new ticket system only for status.

Status model (normative). One ordered scale (-1 … 7): Decision (0–2), Documentation (3–4), Implementation (5–7). Authors set one attribute on <main>: data-adr-weight. That number is the current milestone. The UI shows Current status and the Status log (green = done; yellow = current step except Implementation: Done, which stays green when it is current; gray = not reached). Code: docs/assets/docs-nav.js (renderLifecycleStatusBlocks). RFCs under docs/rfc/ use the same scale with data-rfc-weight on <main> (see RFC index).

The ADR HTML template is the starting shell: data-adr-weight, optional value table, and sections (Ratification, Context, Decision, …). New ADRs copy that file; they use this model, they do not replace it.

How we mark ADR work

Three pieces — keep them distinct:

1. GitHub Issue (discussion). Use .github/ISSUE_TEMPLATE/adr_discussion.md. Start the title with [ADR] so people can find the thread. Discussion stays in the Issue. Labels are optional; the template and title prefix are enough.
2. ADR page (lifecycle on the site). Set data-adr-weight on <main> so the docs UI shows progress. That is only the published milestone; it does not replace Issue and PR history.
3. Ratification. In the merged ADR, link the Issue, merge PR, and acceptance date so the HTML matches the audit trail.

Roadmap rows in docs/backlog/ use their own status pills. Branch names follow ADR 0017. Those are unrelated to data-adr-weight.

Decision

1. Status model (normative here). Fixed milestones: Decision — Proposed (0), Accepted (1), Superseded (2); Documentation — Draft (3), Ready (4); Implementation — Not started (5), In progress (6), Done (7). Bad data-adr-weight values are clamped in script. This ADR introduced the model; older ADRs may not use it until someone updates them.
2. Ratification. For work after this ADR, put the discussion Issue (ADR template, [ADR] title), merge PR, and acceptance date in the ADR Ratification section (see template). ADRs 0017 and below used older rules; from 0018 on, use this pattern.
3. Documentation changelog. Important changes under docs/ go in docs/CHANGELOG.md. The root CHANGELOG.md is for product/API (see ADR 0013).
4. Docs-only PRs. Pull requests that only change docs (including ADRs) can merge to main before code; code can follow in later PRs.

Consequences

Positive

• One agreed status semantics for all ADRs; the template and JS stay aligned.
• Readers see current milestone and full log without leaving the page.
• Discussion and ratification remain auditable via Issues and PRs.

Trade-offs

• Authors must update data-adr-weight on <main> when the milestone changes.
• Legacy ADRs may lack weights or ratification blocks until edited.

References

• ADR template (0000-template.html)
• ADR 0001: Docs as Code
• ADR 0013: Changelog and release notes
• Documentation pipeline
• Issue template: .github/ISSUE_TEMPLATE/adr_discussion.md

Page history