Change Logs: The Treasure Maps of Committed Code

Change Logs: The Treasure Maps of Committed Code

Picture this: Your team is working hard, landing commits, shipping them out the door, and then something hits a snag.

You might use a source tool to narrow down the error message that came up. Or maybe pick apart a test that failed to find out why there is suddenly something mucked up in the code. You may even swim through a sea of commits in an attempt to find the one that might have possibly caused the issue, especially if you didn't find it in the last commit. 

There is a simple tool that could help you and your customers. Using a change log can give a team several advantages. 

1) You can group commits into a timeline and apply them to a known release window.

2) You can view multiple groupings in the same chronological change log. This could present a pattern that might help track down the issue.

3) Your customers can also read the change log and know what they are receiving in the latest patch, update, or release you've deployed. 

4) You can automate the creation of the change log with commit messages. This also reinforces good commit message practices, which further helps with code hygiene. 

I'm not sure where or why the change log was abandoned for commits being the only record. I have a feeling it went about the same time as code comments because the code should be “readable.” Like commit messages should tell you everything you need to know about what was committed. 

However, humans create code, they create commits, and often, even if there is a code review, the commit message isn't necessarily the priority of the reviewer. As long as it's readable now, who cares?

The problem with that kind of thinking about commit messages and code comments is that once you've moved past the shared context, it's lost to time. Customers might guess, but often they'll end up asking questions, and then you might end up asking questions yourself like “What did I mean by that anyway?” or “When did we ship the bug fix?”

Commits and code are like looking for buried treasure. Even if you have tools that could bisect the code and find the problem. It could take that tool minutes to hours. If you had a change log, you might narrow the search or pinpoint it better. 

This works best when you have code you're maintaining, or isn't often updated but needs to stick around. Active code bases might not need change logs. There might be good reasons to skip the practice of creating a change log (though I can't think of one). 

If you're not using one now, ask yourself why? What's keeping you from creating one, especially if it could be automated?

There are several blogs and even a git repo with a tool that can help you automate your commit messages. 

Here's one I liked: What is a Change Log and How To Generate It

Investing two hours in setting up a change log could save you days later. This is for ANY code base, not just prod code, but infrastructure, test harnesses, any code that's over five commits big, you should seriously consider a change log. 


Most Read Posts

Ready, Tester One? *GO!*

Learning From Failure: The Tricky iOS Environment

Postman In The Pipeline: Newman Delivers