The changelog as a war story

A commit message says what changed. It rarely says what was tried and rejected, why the obvious alternative is wrong, or what must become true before the workaround can go. That has nowhere to live in a normal repository, so it is re-derived by someone who did not know it existed.

The practice: one tracked markdown file at the repository root of dated entries in the project's own vocabulary, read before touching an unfamiliar area — in the same review, diff and history as the code it describes.

A useful entry is not a summary. It carries four things:

• Symptom — what a person saw, in the words they would have used.
• Mechanism — why that happened, at the level where the fix makes sense.
• What was ruled out — the plausible alternatives that were tried and did not work, named explicitly so the next reader does not spend the same rounds on them.
• The exit condition — what would have to change upstream, or in the platform, for this entry to be deleted.