Better Issue Tracking

This post isn’t about RavenDB, at least not directly. In Hibernating Rhinos, we use all sorts of tools to communicate. It moves from email (direct, groups, and mailing lists), Slack, Skype, bug tracking, and the odd face to face interaction thingie.

The problem is that some of these discussions happen in different circles, for example, a few devs working on the UI might talk with each other and make decisions about what we need to do, and then later a bug pops up with a “fix the interaction of the replication components” message. This is particularly bad when we are doing this face-to-face, but it can also be something like: “Optimize the process as per the Slack discussion” or “The example that led to this bug is a perfect model of Foobarism.”

There are two problems with this approach. First, if you weren’t part of the discussion, and usually you wouldn’t be, this is like sitting in a cafe with your parents and their high school friends, listening to them talking about other high school friends. It is both a pain and utterly incomprehensible. The other problem is that even if you were part of the conversation, you might not be able to connect the dots to this particular bug report. Or worse, it might be you a few weeks or months later, looking at the bug report and wondering what was going on there.

This is especially the case when we investigate something a few months or years after the change was made, and we do some archaeology to figure out what is actually going on there. At that time, you might look at a piece of code, run blame to see where it came from, track down the specific commit, and issue number that were responsible for the change and end up scratching your head and trying to figure out what was meant there, because the text assumes context, not in evidence.

The other side here is that we can create dozens of issues per week, and they range from “move the text so it will align in this view” to “fix the race condition on failure of recovering node on the cusp of promotion.” Some of them are worth further treatment, with full explanation and discussion, but a three-day chase to resolve an issue that ended up needing to move a piece of code three lines higher isn’t going to get a good description.

What we do need to pay attention to is that we leave enough information to figure out what the story was behind the issue, without making it a chore to actually create issues.