Skip to main content

ADR 002: Adopt Architecture Decision Records

  • Status: Accepted
  • Date: 2026-06-11
  • Deciders: Project owner

Context​

As GospeLib grows in scope (plugins, study maps, scholarly features, desktop and mobile shells), architectural decisions are made across milestones by different contributors. Without a written record, the rationale behind past decisions is lost, leading to repeated debates, accidental reversals, and onboarding friction for new contributors.

Decision​

We adopt Architecture Decision Records (ADRs) as the standard mechanism for documenting significant architectural choices in GospeLib. Each ADR is a Markdown file in docs/adr/ numbered sequentially (NNN-short-title.md).

Format​

Every ADR follows this structure:

  • Title: ADR NNN: <Short Descriptive Title>
  • Status: Proposed | Accepted | Deprecated | Superseded by ADR NNN
  • Date: ISO 8601 date of the decision
  • Deciders: Who made or approved the decision
  • Context: The forces at play, why a decision is needed
  • Decision: What we decided and the details of the approach
  • Consequences: Positive, negative, and neutral outcomes
  • Alternatives Considered: Other options evaluated and why they were rejected

Conventions​

  • ADRs are immutable once accepted. If a decision changes, a new ADR supersedes the old one (the old ADR's status is updated to Superseded by ADR NNN).
  • ADRs are numbered monotonically starting at 001. Do not reuse numbers.
  • Keep ADRs concise but self-contained. A reader should understand the decision without needing to read other documents.
  • Store ADRs alongside the code they govern, in docs/adr/.

Consequences​

Positive​

  • Architectural decisions are discoverable and searchable.
  • New contributors can understand why things are built a certain way.
  • The immutable record prevents silent reversals of past decisions.

Negative​

  • Writing ADRs takes time. Trivial decisions should not require an ADR.

Neutral​

  • The docs/adr/ directory will grow over the lifetime of the project.

Alternatives Considered​

Wiki pages​

Wikis are editable by anyone and lack version history tied to the codebase. ADRs in the repository travel with the code and are reviewed via pull requests.

No formal process​

Relying on commit messages and PR descriptions for rationale. This scatters context across hundreds of PRs and makes it hard to find the "why" behind a specific design choice.