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. 


Comments

Post a Comment

Most Read Posts

Ready, Tester One? *GO!*

"I handed my passport to the immigration officer, and he looked at it and looked at me and said, 'What are you?'" - Grace Hopper (60 Minutes Interview) The Grace Hopper quote above always makes me think about my job as a tester. Companies that develop software know they need testers, but they generally have hard time figuring out what testers are and what skills they need in the role. There have many discussions about how testers can be more technical and at some point, coding comes up in the conversation. My response on twitter contained a few things on a list I have, which I created for a client, so they could have a checklist of skills. This checklist was a guideline to determine the skill level of the tester applicant. This is by no means a complete list and I would be open to additions to the list. Feel free to add those to the comments or tweet them to me. For clarity, I took the list of skills I had and broke them into levels. I like games and I lik...
Read more

Learning From Failure: The Tricky iOS Environment

"You build on failure. You use it as a stepping stone. Close the door on the past. You don't try to forget the mistakes, but you don't dwell on it. You don't let it have any of your energy, or any of your time, or any of your space."  - Johnny Cash There are times when our work, as a team, as testers on a team can give us insight into how we can improve things for the overall success of the product. Often those things are issues or defects which can present themselves at the most inconvenient times, in the most inconsistent ways. When we can learn from them and improve things for everyone on the team, the team benefits. When the team owns the defects and the testing strategy, not only the testers, then customers benefit as well. I was working remotely verifying a release and only had simulators and emulators to work with as I was testing mobile builds. Often folks mistrust builds which only use emulated software and not real devices for fairly good reasons...
Read more

Postman In The Pipeline: Newman Delivers

Image
  It's not me, it's the songs.  I'm just the postman,  I deliver the songs....  - Bob Dylan Recently, I've had the chance to work on a project with some other awesome folks which has involved creating a BFF - A back end for front end service. This allows the app to access several API and aggregate calls into something the app can use, or lets the app send information to the BFF for several APIs to receive. Part of the code coverage for the BFF was creating some simple tests with Postman around the business logic and interactions. Learning About Postman I did lots of reading. Lots of reading how others has done things (Danny Danton - big props for being a super help!). Eventually, I came down to a small set of tests which could give us some accuracy about our BFF pipeline and the APIs we were accessing with it. Postman has a couple of options for this, global variables, environmental variables, and plain variables. One of the first problems I came acros...
Read more