Ever wonder what that idiot was thinking when he checked in a change that completely broke a piece of software, typically right before a deadline? Ever wonder if anyone’s thinking that about you?
I recently read a draft book by Paul Myers, on the topic of content. And he has some great information about how to write articles, books, blog posts, and a lot of other stuff in this book (not currently available, I’m afraid – but keep an eye out).
One thing he didn’t cover, though, is changelog messages for a source control system. I suspect he didn’t cover it because a vanishingly small group of people, of whom he may not be one, have ever had to write such a thing. So, just because I think the topic’s interesting, here’s my thoughts.
First, identify your purpose.
The purpose of a changelog message is to explain to a future reader what the purpose of a change was. Simple. It’s always this; if that weren’t the purpose, it wouldn’t be a changelog message. But you have to keep it in mind. The purpose is not to fill in a checkbox on a process so you can keep your statistics up. It is not to keep the CVS server (or git, if you’re lucky!) from being lonely in the night. It is to explain the change.
Fulfill that purpose.
This is harder than it sounds to do well – but not too hard if you keep the purpose in mind.
It is not enough to identify the change. Explain the change. I’m sure just about every programmer has seen an example to the effect of:
pre. // increment i
++i;
“Fix bug in kernel” is no better. So how do we explain the change? Start with the basics. What is the effect of this change? What were things like before? What are they like after? Are you fixing a bug or adding a feature? Why is this the correct fix?
Go a bit further, too.
In many cases, you’ll find that the bug was hard to fix. In those cases, be sure to at least mention the wrong turns, and why they were wrong turns. If you came into this utterly convinced that it was a fencepost error and the solution would be to add the obviously-required “+1” to an expression, only that didn’t help, mention this.
Don’t worry if this makes the message a bit long. The source code repository is not going to run out of room because of a twenty-line explanation at the top of a fix, even if the explanation is longer than the fix. Do worry that you’ll omit it and the next person to touch the code will end up reproducing your earlier mistakes before understanding the code.
The changelog is like a timestamped comment.
One of the worst things about writing up a detailed comments explaining what is going on in code is that future revisions to the code may make the comments invalid. What you really want is some kind of mechanism to let you put a comment on the code that is somehow tied to the code’s state at a given time.
That’s the changelog. Use it. Be verbose. Be descriptive. Explain not just what you did, but why. Explain what else you tried and why it didn’t work. Explain how you diagnosed the problem.
Sooner or later, you will be that idiot who checked something in that broke the software. What is most important is not that your coworkers not think you’re an idiot – I can’t help with that – but that they can find out what you were thinking without waking you up at 3AM.