About these records
These pages record decisions that shaped the system, and the reasoning behind them.
They exist because the reasoning is the part that gets lost. The code shows what was decided; it rarely shows what the alternatives were, or why they were rejected. Without that, a future contributor either re-litigates a settled question or reverses a decision without knowing what it was protecting against.
What belongs here
A decision worth recording is one that was not obvious, that had a real alternative, and that would be expensive to reverse. Choosing a framework qualifies. Choosing a variable name does not.
The format
Each record states the context, the decision, and the consequences, including the ones that are inconvenient. A record that lists only advantages is marketing, and it will not help anyone deciding whether the decision still holds.
They are not updated
A record describes a decision at the time it was made. If a decision is later reversed, the old record stays as it is and a new one supersedes it. Editing history to look consistent destroys the thing that makes these useful.