Skip to content

0001 decision records

github-actions[bot] edited this page Nov 18, 2026 · 1 revision

Decisions are recorded

Status: accepted · Implementation: done · Date: 2026-11-18

The format is the one LibreLifts uses (its ADR 0001), with two changes: implementation is only planned or done, and notes may be added to after the fact.

Context

LibreBars starts from an empty repository. Its architecture and its way of working come from LibreLifts, a sibling project by the same maintainer, where each choice was written down as a record and then built. Copying the outcome without the reasons would lose the part that is hardest to get back: why things are the way they are, and what was given up.

Decision

Every decision that shapes the project gets a short record in docs/decisions/, written before the decision is acted on.

  • One file per decision, named NNNN-kebab-title.md, numbered in order.
  • Front matter: title, number, status, implementation, date, supersedes, superseded_by, notes.
  • status is accepted or superseded. implementation is planned or done.
  • Three sections: Context, Decision, Consequences. Consequences say what is given up, not only what is gained.
  • A changed decision gets a new record that supersedes the old one. Old records are never rewritten. Only their status, superseded_by and notes change, and notes only gains facts: what was built, when, and where the build differed.
  • A record taken from LibreLifts is written again for LibreBars, with its own number, and its notes name the LibreLifts record it came from.
  • docs/decisions/README.md lists every record with its status.

Consequences

  • A decision costs a few minutes of writing before any code.
  • The history of why stays in the repository, next to the code. Superseded records stay too, so the folder also shows what was tried and dropped.
  • The numbers here do not match LibreLifts' numbers. Someone comparing the two projects has to go through the notes.

LibreBars

Clone this wiki locally