The README Lied
The README said one thing. The commit history said something else entirely. The commit history was right.
I was onboarding to a codebase I'd never seen before. The README was thorough — setup instructions, architecture overview, a section on "design decisions" that explained why certain things were built the way they were. I read it carefully. I followed the setup instructions. I started reading the code.
Something was off. The code didn't match the README's description of the architecture. Not dramatically — it wasn't wrong, exactly. But the README described a system that had clearly been refactored at some point, and the README hadn't been updated to reflect the refactor.
Reading the History
I ran git log --oneline and started reading. The commit history told a completely different story than the README. There had been a major refactor eight months ago. The commit message said "restructure auth flow — see PR #247 for context." PR #247 had a detailed description of why the old approach was wrong and what the new approach was trying to do.
That PR description was better documentation than the README. It explained the actual reasoning, the tradeoffs, the things that had been tried and abandoned. The README described the system as it was supposed to be. The commit history described the system as it actually became.
The the terminal archive has the full terminal archive. And the core has some related thinking on observability — the gap between what your documentation says and what your system does.
What Commit Messages Are Actually For
Most commit messages are terrible. "fix bug," "update," "wip," "asdf." These are useless. They tell you that something changed but not why, not what was tried before, not what the tradeoffs were.
Good commit messages are documentation. They're the only documentation that's guaranteed to stay in sync with the code, because they're attached to the specific change that made the code what it is. A good commit message answers: what changed, why it changed, and what you considered but didn't do.
The tarosyn dev has some thoughts on this from the tarot dev side — the challenge of documenting systems that are inherently ambiguous. And josephcalitoy.com has some personal notes on the human side of documentation — why we write it for our future selves and then fail our future selves anyway.
The Practice
I've started writing commit messages as if I'm writing to someone who will need to understand this change in two years with no other context. It takes longer. The commits are better. The codebase is easier to work in. The README is still wrong, but at least now I know where to look for the truth.