What makes a commit message useful six months on

Back to list2023-10-25
You

What makes a commit message useful six months on?

ChatGPT

The why. The diff already shows what changed; what it cannot show is the constraint that made the change necessary, the option you rejected, or the bug number that explains it.

You

Our README is thorough and nobody reads it. Why?

ChatGPT

Because it answers questions in the author's order, not the reader's. Lead with what the thing does in one sentence, then how to run it, then the caveats. Anything a reader cannot act on in the first screen is reference material and belongs further down.

You

What belongs in a changelog entry?

ChatGPT

What changed for the user and what they have to do about it. Internal refactors do not belong unless they change behaviour, and "various bug fixes" is a line that costs attention while carrying nothing.

You

Is there a simpler version that gets most of the benefit?

ChatGPT

Yes: do the first step, skip the automation, and revisit in a month. Most of the value is in the first step, and most of the cost is in making it repeatable before you know it is right.