Record architecture decisions#

  • Status: Accepted

  • Date: 2026-05-29

  • Deciders: saia-python maintainers

Context and Problem Statement#

saia-python is small but makes non-obvious design choices (optional integrations, response shapes, concurrency). New contributors — and our future selves — need to know why a thing is the way it is, not just what it does. How do we capture that rationale durably and close to the code?

Decision Drivers#

  • Rationale should live in the repository and be versioned with the code.

  • The format should be lightweight (Markdown) and render in the Sphinx docs.

  • Decisions should be append-only history, not silently edited away.

Considered Options#

  • MADR (Markdown ADRs) committed under docs/adr/.

  • A single freeform DECISIONS.md.

  • An external wiki.

  • No formal record (rely on commit messages and the CHANGELOG).

Decision Outcome#

Chosen option: MADR under docs/adr/, because it keeps rationale next to the code, versions it through Git, renders in the existing MyST/Sphinx docs, and gives each decision a stable, citable ID.

Consequences#

  • Good — rationale is discoverable from the rendered docs and reviewable in PRs.

  • Good — superseding is explicit (a new ADR references the one it replaces).

  • Neutral — a small per-decision authoring overhead; only significant decisions warrant an ADR.

Confirmation#

The docs/adr/ tree is part of the Sphinx toctree and built under sphinx-build -W, so a malformed or orphaned ADR fails CI.

More Information#