A sort of bug tracker

All bug trackers suck. That's why Abhijit and I really don't want to use one for aox.

Here's what we do instead. It's subtle.

There's a notes file in the version-controlled source tree. The only way to add to a note (ie. file a bug) is to make us do it. There are some scripts that look at the file.

The notes file and SCM

The notes file is very mildly structured. Basically anything can go in that we want to add. This is an important point: Adding to this, or working with it, requires hardly any effort. Understanding what to add requires mental effort, but the procedure of adding does not. (At the same time there is some structure, enough that reporting scripts can extract useful information from the file.)

There are no required fields to fill in, there's not even any need to change to a different program. The drawback is that it's impossible to append screenshots or other data.

The file is version-controlled along with the files it's about. The regular commands to look at versions and review new changes for the source code apply. The atomic commit that resolves a bug also updates the tracking file.

I suspect that version-controlling it separately wouldn't work as well. I don't have any rational arguments, but intuitively I think that bug-tracking needs to be closely tied to the source code it tracks in order to work well.

Receiving bug reports

There's no way for an end-user to talk to the bug tracker. End users can send mail, and someone such as I must answer the mail and make notes as required.

This is a feature, not a shortcoming. Answering the mail is a chore, but it's not (much) worse than handling user-supplied bugs in typical bug trackers, and the results are better.

Classic bug trackers have a great advantage if most bug reports don't need to be handled by a human, or aren't handled by one. Three examples of many: The program has a feature that users report as a bug. Users report supposed bugs because they didn't find the solution to their problem in the (disorganised) documentation. The developers only fix bugs that are relevant to their own use of the code.

Statistics, reports, notifications, etc.

The notes file is version-controlled, and all decent version control systems are able to run user-provided code when a file is updated.

We use git. git hooks can look at changes to the notes file and do anything, including update a web-accessible list of open bugs, notify people via email or jabber, etc. We don't do any of that, but it's possible.

The structure we use is simple: A single-line headline, one empty line, optional body text indented two spaces or more, magic lines at the end, also indented.