Decision records¶
Each page here records one decision: what was decided, when, why, and what it cost. They are short on purpose. The full reasoning lives in the design specification, and each record links to the section that argues its case.
The records were written while PyFr's reference service — the service this project was generated from — was being built, and records 1 to 12 were backfilled after the work they describe. The "Decided" column names the PyFr milestone (M0, M1, …) that made each decision — PyFr's roadmap says what each milestone built — and a record is dated to that milestone rather than to the day it was written.
Why they are never edited¶
An accepted record is history. It says what was decided on a date, given what was known then. Changing your mind means writing a new record and marking the old one superseded — never rewriting the old one, which destroys the only account of why the software is the way it is.
For the same reason, records are exempt from the review-date warning that covers every other page on this site. A decision does not go stale.
Adding one¶
Copy template.md, take the next number, and add it to the
nav in mkdocs.yml. Write it when the decision is made, while the
alternatives are still fresh — a record written six months later is a
reconstruction, and it shows.
The records¶
Three decisions belong to PyFr, the template this project was generated from, and are recorded on its site: cookiecutter over Copier and cruft (0002), uv over pip and Poetry (0003), and the template is the source of truth (0017).