Skip to content

Decision records in rendered projects

Context and Problem Statement

A small tool does not need a decision log, and an empty docs/decisions/ folder is clutter. A flagship project does need one, because its choices are costly to reverse.

Considered Options

  • Every project gets docs/decisions/
  • No project gets it
  • A copier question, on for flagship kinds and off for small tools

Decision Outcome

Chosen: a copier question. It defaults on for flagship kinds and off for small tools. A rendered project never gets an empty folder: it starts with a first real record.

The question is decision_records. It defaults on for the web-service, data-pipeline and web-app kinds, Compose-only repos and Silver-badge projects. The first record says the project starts from this template, with the answers that shaped it.

Consequences

  • Good: records only where they earn their place.
  • Bad: one more question to maintain, and a kind-to-default mapping to keep current.

Confirmation

scripts/check-render.sh asserts the folder and its first record in a Compose-only render, and no folder in a research render without a badge.