How Do You Maintain Your Change Log?
We're coming up to that point in development again where we need to do up a change log for a release. Ephox has never really gotten this process down pat so it inevitably leads to trawling through a back log of subversion commit logs and bugzilla reports. It always feels like there should be a better way to do it, but it's always too easy to forget to add something to the change log if you try to keep it up to date all the time.
Doug suggested today that the XP approach to change logs would be to keep it up to date each iteration. Since each iteration is a release - even if in our case it doesn't always go out to end users - it should be documented as such. The net result would be that when we release we just need to combine the change logs from the iterations since the last release. It's something that could be added in to my Monday morning iteration clean up and kick start. I'm already pulling the completed story cards down off the wall and noting down the weeks velocity. It shouldn't take too much to add change log entries for each of the completed stories as well. Then we just need to be strict about never changing anything without a story card which isn't too far from the situation today.
Is there a better way? How do other people handle change logs?
October 17th, 2006 at 12:14 am
On projects I participate in, we’re closer to the XP approach but not quite. The changelog is a file in our source code control system, with a section for each release — very simple. Every time a developer addresses an issue, he or she updates the change log with what they’ve done. If the issue was in our issue tracker, the developer adds a link as relevant. That’s it. The change log is always (or almost always, as humans are imperfect) up to date in SVN. The release manager has little to no work to do when cutting the release.
October 17th, 2006 at 1:19 am
Switch to JIRA - it will generate release notes for you, as long as your disciplined about the fix version number.
October 17th, 2006 at 7:21 am
There are a couple of problems with just using an automated report from a bug tracking tool:
1. Not all changes to the product are because of bugs. We add new features too. :) Our features are tracked on story cards so that we can pass them around and physically see our progress through the iteration. It’s working really well and I’m not keen to change it. We also have a public facing support system that occasionally requires bug fixes and we don’t want the overhead of having to log the issue in the bug tracking system when it’s already documented in our support system.
2. Not all bug fixes need to be included in the change logs. During a release we quite often find bugs in the new features which have never been released to clients. It would be silly to have a bunch of entries in the change log reporting that we fixed problems that no user could possibly have ever seen.
We’re also quite happy with bugzilla for now and the ultimate aim is to get rid of the existing back log of bugs and ditch bug tracking systems altogether. Instead whenever we find a bug it will be fixed immediately and short of that, written on a story card and scheduled like any other work.
October 17th, 2006 at 8:48 pm
Why not just use a subversion hook script to log the commit message on each checkin?
October 17th, 2006 at 10:01 pm
Because not all check-ins should be reported to end users. A subversion hook, or a log command, is one option we’ve looked at but since not all check-ins should be reported it requires discipline to make sure the specific format is followed. We’ve also found that as developers we like to have our commit comments describe what we changed in the code, not what the user needs to identify what changed. I’d like to find a process that fits in with the way we work without making us contemplate the change log all the time.
October 18th, 2006 at 11:32 pm
I’d add a vote to Doug’s plan, keeping the file up to date when ticking off story cards would work well. Perhaps making updating the file part of the reward for finishing off a story would be nice.
Given that story cards are the way of tracking work (if JIRA was how this was done, things would change), then this would be a good strategy to try.
Moving the bug fixes to story cards would be a good approach to follow as well. As already suggested, the idea of including the bug fixes in the mix of story cards would help this process, and might also help tracking velocity.