Tuesday, 8 January 2013

A bazaar hook to reduce VCS meta-data asynchrony

What changed?

Sometimes, when using VCS systems such as bazaar, there is a tendency to forget to perform the necessary 'book-keeping' for those not using it because you get so focused on the tooling itself.

Most VCS systems expect the author to provide a brief explanatory message per commit. This log is invaluable since it (hopefully!) provides insightful context into the programmers intentions. However, that meta-data is only available to those with a copy of the branch/checkout/stream/view or whatever your VCS calls it.

But what about those who only come into contact with the project via release tarballs for example?

I'm thinking specifically of changelogs. Debian and Ubuntu provide the incredibly useful 'dch' (aka debchange) tool which synchronises the VCS commit message with the latest 'debian/changelog' file entry. But what if you're not working on a Debian project? When you're working on a fast-paced project, or just working at a particularly fast pace, it's easy to forget to update the top-level changelog in addition to providing your usual VCS commit message. If and when you remember or notice they have gone out of sync, you can of course create a new commit purely to "sync up" the VCS commit log with the actual changelog file. But having to do that is annoying. I hit this issue recently and duly put bzr to work to help avoid this situation in the future.

bzr hooks to the rescue

A minor tweak to my bzr pre-commit hook that checks for signs of unfinished work was all it took to solve this for me. What that hook now does is to also offer to abort the commit if:

  • the commit would change files below the debian/ directory, but debian/changelog has not been updated.
  • the commit would change non-debian-directory files, but the top-level changelog has not been updated.
  • both the top-level and the debian changelog have been modified (shouldn't generally happen at the same time).
  • both debian and non-debian-directory files have been modified (shouldn't generally happen at the same time).



If a bzr hook causes the commit to abort, you will lose your pending commit log entry text! Unfortunately, there doesn't appear to be a public API to allow hooks to save the text to a file (but please tell me if I've missed this!)

I hadn't noticed this issue since I generally commit having pre-prepared a bzr commit log entry ("bzr commit -F /tmp/commit.txt") so didn't notice this until recently.