How to Report Bugs Effectively

I'll be having more to say on what I would like to see in MOC bug reports after version 2.5 is out and I have more time to do so, but I recently reread an essay by Simon Tatham and it agrees with much of what I would have to say.

I first read it many years ago from a contract programmer and FOSS user's point of view. I thought it was good then, but I was somewhat shielded from end user bug reports by support staff. Now, rereading it as a FOSS developer, it resonates with me much more deeply.

Not only does his essay help to inform users how to report bugs, it also explains (in user-friendly terms) the process we programmers need to go through to locate and fix the bug. Knowing that, users will understand why programmers ask the questions they do and how to answer them appropriately.

Simon says of programmers:

They will want to know lots of details about your computer, so they can work out how it differs from theirs. A lot of these details will depend on the particular program, but one thing you should definitely be ready to provide is version numbers. The version number of the program itself, and the version number of the operating system, and probably the version numbers of any other programs that are involved in the problem.

I would go further and say that you should always provide the MOC version you are using in the initial report. It is easily obtained using mocp --version but is so frequently missing from MOC bug reports. It is important because repeatedly asking for it is time wasting, and trying to reproduce the problem without it is pointless. I'm seriously considering just ignoring bug reports which do not include it.

An obvious implication of posting a bug report is that I will need to talk to you; be prepared to talk to me. I may not do so immediately, so it's important that you frequently monitor the thread on which you reported your problem. But there is only so much can be done on the Forum, and at some stage I may well have to continue the conversation by e-mail. Please make sure that the e-mail address you registered with is one on which mocmaint can talk to you. If I can't talk to you I probably can't fix your problem (and probably won't try very hard).

Don't stop talking to me half way through (at least, not without explanation). If you do that, you're wasting the time of both of us and it would probably have been better if you hadn't posted the problem at all. Worse, you may have stopped someone else who was serious about finding a solution posting the problem themselves.

If you find a solution to your problem yourself, let us know! If it's a MOC issue, then maybe improvements can be made; if not, then at least I won't waste time by continuing to work on it. Others may also be experiencing the same problem and could benefit from your solution.

Simon also says:

In this essay I'll try to state clearly what makes a good bug report. Ideally I would like everybody in the world to read this essay before reporting any bugs to anybody. Certainly I would like everybody who reports bugs to me to have read it.

I, too, would certainly like everybody who reports MOC bugs to have read it.