Skip to main content

Short imperative title

How to use this template
  1. Copy this file to docs/adrs/NNNN-short-title.md (sequential numbering, 4 digits).
  2. Update the frontmatter:
    • status: Proposed while under discussion, Accepted once signed off, Superseded when a later ADR replaces it (in that case, uncomment superseded_by with the successor's number).
    • date: date of the decision (or of the proposal if still Proposed). Must be quoted so YAML does not parse it as a Date.
    • deciders: those who sign off on the decision. Use GitHub handles with @.
    • involved: those who were consulted or contributed but do not sign off. Also accepts teams (@org/team).
    • discussion: do not fill this in manually. This ADR originates from a GitHub Discussion (category Ideas). When someone comments /adr on that Discussion, the adr-from-discussion workflow bootstraps this file with discussion: <number> already populated. The original Discussion remains as a permanent follow-up thread.
    • slug (optional): add slug: NNNN-short-title if you want the URL to preserve the numeric prefix (Docusaurus strips it by default).
  3. Update sidebar_label to something like ADR-NNNN — Short description.
  4. Delete this :::instructions block.
  5. Fill in the sections below. The H1 and metadata are rendered automatically — do not write # ADR-NNNN: ... or manual Status/Date/Deciders lists; the frontmatter is the source of truth.

Context​

What situation or problem we are facing. Include relevant constraints (technical, budgetary, timeline, organizational). Avoid prescribing the solution here.

Mention people with @handle — they are automatically converted into links to their GitHub profile (e.g. @andylow92).

Decision​

What we decided to do, in an imperative sentence. Include enough detail so an outside reader understands the "what" without ambiguity.

Consequences​

  • Flat list of implications derived from the decision, mixing positive, negative, and neutral.
  • Be honest about costs: negative consequences go here too, not in a separate ADR.
  • If a consequence has a clear mitigation, describe it on the same line.

Alternatives considered​

  • Alternative A: brief description and why it was rejected.
  • Alternative B: brief description and why it was rejected.

References​

  • Links to documentation, issues, PRs, relevant articles.