Architecture Decision Records (ADR)

An Architecture Decision Record (ADR) captures an important architecture decision along with its context and consequences.

Conventions

• Directory: contributing/decisions
• Naming:
  • Use date-prefixed files: YYYY-MM-DD-choose-database.md
  • If the repo already uses slug-only names, keep that: choose-database.md
• Status values: proposed, accepted, rejected, deprecated, superseded

Workflow

• Create a new ADR as proposed.
• Discuss and iterate.
• When the team commits: mark it accepted (or rejected).
• If replaced later: create a new ADR and mark the old one superseded with a link.

ADRs

• Adopt architecture decision records (accepted, 2026-03-11)