Lessons From a Changelog

For the first few years that I worked at Ephox there was a regularly recurring problem: how to let our clients know exactly what’s changed between versions. We were good at showing off the new features but never had an accurate list of which bugs were fixed and every so often a client would ask for that. It seems simple enough – just keep a changelog – but there were some challenges.

• Our support system is separate to our bug tracking system so fixes can come from either source (the support cases are always fixed immediately so they don’t need tracking). You therefore can’t just pull a report from the bug tracking system to see what’s been fixed.
• If you had to manually update a change log developers kept forgetting to do it and it would be inaccurate.
• Going back through the subversion commits at the end of the release worked but took way too long and was the kind of job you wouldn’t wish on your worst enemy.

Today though, we’ve got a very accurate changelog that’s published out for every release and kept up to date enough that it’s published along with every nightly build. So what changed?

We put a checklist on the wall to make sure that a story was really “done done” before developers could move it over to the completed side of the planning board. That checklist included updating the changelog. From there it became habit and if someone forgets to update the changelog it’s generally noticed by someone else pretty quickly.

What makes checklists so powerful is that they scale so well with the user. If you’re a beginner the checklist provides a set of steps you need to go through to get the job done. If you generally know what you’re doing but it’s still not routine, the checklist provides a handy reminder. If you’re an expert it only takes a moment to flick through the checklist and ensure that everything was done, and it’s still there to remind you if you forget something or are interrupted part way through.

It’s amazing how many lives checklists can save. Dr Peter Pronovost set up a checklist for basic hygiene practices at Johns Hopkins Hospital and it “slashed Michigan’s central intravenous line infection rate by 66% and quarterly infection rate to zero”. Similarly, every time you fly you put your life in the hands of a great big checklist that the pilots, ground crew, maintenance teams, flight attendants and everyone else involved go through to make sure that the plane is ready to fly, that the passengers are safely on board and have been screened correctly for security etc.

So, next time you need to get your team into a good habit, find out what process that habit should be part of and create a checklist that includes it. Not only will it get people into a good habit, it will provide an essential training guide for your next new employee.