selamy-labs Source-History Decision Log
Source control isn't only a safety net — it's the project's decision log. The code's current shape is the residue of past decisions; most odd-looking lines are fixes for something that already bit someone. Read the history before you change code, so you build ON accumulated learning instead of re-deriving dead-ends and re-introducing solved bugs.
Reading history is how you iterate. Skipping it is how you oscillate — fixing a symptom, hitting the next, sometimes re-breaking the first.
The one practice that matters most
Before changing fragile / recurring / high-stakes code: git blame the lines and read the last few relevant commits + PRs, then state in your change what prior decision you are preserving or deliberately reversing. If you can't say why the code is the way it is, you're not ready to change it.
The habit
- Blame before you change.
git blame/git log -pthe specific function. Don't undo a fix you don't understand. - Follow the "fix-the-fix" chains and reverts. A chain of
fix:commits or a revert marks a landmine that has bitten before — read each; the history names the failure modes. - Read PRs, not just commits. Descriptions and review threads carry the why and the rejected alternatives the diff can't show.
- Check before you re-try.
git log --all --grep=<concept>— a reverted commit is a tried-and-failed approach; read why before re-discovering the dead-end. - Fix the class, not the instance. When fixing a bug, search history for the same class. If one fragility recurs in different places, the real fix is the class — and a prior fix's message often already names the pattern you're about to re-learn the hard way.
- Write the log you'd want to read. Commit and PR messages are the decision log for the next person. Capture the why, the alternatives, the rationale — never "wip" / "fix". Read to learn; write to teach.
When to use / when not
- Use it for fragile, recurring-issue, live, security, or otherwise high-stakes code; before "fixing a fix"; before re-trying something; and whenever you — or a fresh session, or a different teammate — lack the context a long-tenured maintainer would carry in their head.
- Don't over-mine. Greenfield or trivial changes need little archaeology. Target the specific lines and the relevant chain, not the whole repository's history. Scale the effort to the stakes, the same way you scale testing.
Why it matters
The current shape encodes hard-won lessons. A prior commit message often already names the pattern you are about to re-learn — generalizing it sooner is the entire point of iterating. For a team — and especially for many contributors working across separate sessions — the history is the shared long-term memory: reading it is how a context-blind newcomer acquires the maintainer's intuition instead of re-deriving it badly.