Against the tidy changelog

Bach’s autograph manuscripts are full of corrections. Notes scratched out, staves re-ruled, a better idea crammed into a margin that was not left wide enough for it. The fair copies are beautiful and tell you nothing. The working manuscripts tell you where he changed his mind.

We have decided, collectively, that a changelog should look like a fair copy. Squash the branch. Rewrite the history. Present the work as though it went in a straight line from problem to solution, because that is tidier to read.

It is tidier. It is also the only part that was worth keeping thrown away.

The information is in the reversal

When I come to a piece of code I do not understand, the question is almost never “what does this do” — I can read. It is “why is it like this and not the obvious way”. And the obvious way was usually tried. It is in the history, three commits before the current shape, with a message like revert: doesn't work with timezones.

A squashed branch deletes exactly that. What survives is the answer with the working removed, which is the one form in which an answer cannot be checked.

The history I want to find looks like this:

$ git log --oneline
4f2a1c9 fix: pin the timezone at the boundary, not in the formatter
9b3e772 revert: "format dates in the component"
1d8c04e format dates in the component

Three commits, and the middle one is the one that teaches. A squash leaves only the first, which reads as though the obvious approach was never tried.

What I do instead

Keep the reversals. Write the commit message that says what you tried and why it did not survive contact. It costs one sentence, and it is the sentence that someone — probably you, in eight months — will need.

Tidiness in a changelog is a preference. Recoverability is a property. They are not the same thing and we keep trading the second for the first.