Architecture Decision Records
ADR sequence for the decisions that govern the shipped GraphForge product
architecture. The table below is the active set: every record in it currently
governs. Superseded records are not deleted — they move to
superseded/ so their reasoning and their inbound links survive,
and they are listed under Superseded records below.
Roadmap-only ADRs are not retained in this tree.
Superseded records
Section titled “Superseded records”Retained under superseded/. Each names the record that replaced
it; nothing here governs.
| ADR | Title | Superseded by | File |
|---|---|---|---|
| 0017 | One version across core and adapters | ADR 0036 | superseded/0017-unified-release-version.md |
| 0033 | Prereleases share one version with per-ecosystem spelling | ADR 0036 | superseded/0033-prerelease-version-identity.md |
| 0034 | One canonical release-candidate spelling, -rc.N |
ADR 0036 | superseded/0034-canonical-release-candidate-spelling.md |
| 0057 | Initial builds resolve edge endpoints by a node-surrogate index instead of two endpoint sorts | ADR 0058 | superseded/0057-endpoint-resolution-by-node-index.md |
Numbering
Section titled “Numbering”ADRs are numbered NNNN-slug.md starting at 0001. A number is used once: it
is never reassigned, and a record keeps its number when it is superseded and
moved to superseded/. Accepted ADRs are immutable; a new ADR supersedes an old
one rather than rewriting it.
Status vocabulary
Section titled “Status vocabulary”A record carries exactly one **Status:** line, immediately under its title,
whose value is one of these four and nothing else:
| Status | Meaning |
|---|---|
Proposed |
Under discussion. Not yet decided. |
Accepted |
Decided and in effect. |
Superseded by ADR NNNN |
Replaced by a later decision. The file lives under superseded/. |
Deprecated |
No longer relevant, and not replaced. |
Status records the state of the decision, not of the code. Where the state of
the implementation is worth recording — shipped, pending, partial, or scoped to
a milestone — it goes in an **Implementation:** field beneath the status, not
in the status value. docs/engineering/adrs/README.md carries the same four
values.
Lifecycle fields
Section titled “Lifecycle fields”Every record’s frontmatter carries status, superseded_by, and revisit_when
(#1625). revisit_when is a one-line observable trigger: the condition under
which the decision gets re-examined. scripts/ci/adr-index.py check refuses a
record without it and renders it in docs/engineering/adrs/README.md. A
decision nothing depends on any more is marked Deprecated rather than left
Accepted.
Related navigation
Section titled “Related navigation”Published Starlight nav: Engineering → Architecture Decision Records (sidebar
entries mirror the active table). ADR bodies stay under docs/adr/; the public
decision log at ../engineering/adrs/ links here and must
not duplicate or renumber bodies. Do not fork a second ADR sequence.
Both indexes and this directory must agree, and so do the two docs-site files
that the published build consumes. scripts/ci/adr-index.py check enforces all
four in make check and the CI Lint job; the docs-site regions are generated,
so run python3 scripts/ci/adr-index.py generate after adding or superseding a
record rather than editing them by hand.