Skip to content

README.md

Latest commit

 

History

History
114 lines (77 loc) · 2.64 KB

README.md

File metadata and controls

114 lines (77 loc) · 2.64 KB
Raw

Architecture Decision Records

This document is generated automatically. Do not edit.

This directory contains the project's Architecture Decision Records (ADRs).

An ADR records a significant architectural decision, the context in which it was made, the options considered, and the consequences of the chosen approach.

When to create an ADR

Create an ADR when a decision:

  • Has a significant effect on system architecture
  • Introduces, replaces, or removes an important technology
  • Changes data ownership or system boundaries
  • Introduces long-term operational constraints
  • Has meaningful security, reliability, performance, scalability, or cost implications
  • Is expensive or difficult to reverse\

Do not create ADRs for:

  • Routine implementation details
  • Minor refactoring
  • Coding style decisions
  • Easily reversible local changes

ADR lifecycle

Proposed
│
├── Accepted
│ │
│ ├── Superseded
│ └── Deprecated
│
└── Rejected

Statuses

Status Meaning
Proposed Under discussion
Accepted Approved and should be followed
Rejected Considered but not selected
Deprecated Still valid historically but no longer recommended
Superseded Replaced by a newer ADR

Naming

Use:

NNNN-short-kebab-case-title.md

Example:

0001-use-postgresql-for-transactional-data.md

ADR numbers are immutable.

Decision records

Creating an ADR

Create a new ADR from template.md and assign the next available sequential number.

The ADR filename must use:

NNNN-short-kebab-case-title.md

Before accepting an ADR:

  1. Complete all required metadata.
  2. Document the considered options.
  3. Record the consequences and risks.
  4. Submit the ADR through the normal pull-request review process.
  5. Regenerate this README.

Changing an accepted decision

Do not rewrite the decision in an accepted ADR.

Instead:

  1. Create a new ADR.
  2. Set the new ADR's supersedes metadata.
  3. Set the old ADR's superseded_by metadata.
  4. Change the old ADR's status to Superseded.
  5. Regenerate this README.

This preserves the architectural history of the project.

Maintaining this index

This README is generated and must not be edited manually.

After creating, renaming, or removing an ADR, regenerate the index:

adr generate toc \
  -i docs/adr/intro.md \
  -o docs/adr/outro.md \
  > docs/adr/README.md

References