It was late in the afternoon. The city was in that quiet period between the lunch time rush hour and the end of work day rush hour. The sun was getting low in the sky. My office blinds were making shafts of light that highlighted the dust particles hanging in the air. I was bored, but looking forward to an early evening date with a bottle of soda and a video stream to my couch.

Suddenly, blam, a letter dropped into my INBOX. Oh, no! So much for my evening plans.

I took my feet off my desk, and opened the missive. It was a report of the worst kind: someone's found a bug, and I would have to get off my gluteus maximus to squash it, and squash it good. I opened my drawer, and took out the key to the hardware cabinet, and strapped a .33 under my left armpit. (That's a .33 liter can of cola, not a gun. Using guns to deal with bugs would be ridiculous, what kind of a thug did you think I am?)

So you have a free software project with users. Sooner or later someone will report a problem that they're experiencing, and this may turn out to be an actual bug in your program that you need to fix. Let's have a short look at how to do that well.

Some recommendations, based on over three decades of writing software:

• You should document how to report issues. Making unhappy users dig for that information just makes them angry.

• You should separate reports of issues separately from confirmed bugs. A bug is something you need to fix, an issue is something you need to investigate what causes it. An issue report is a discussion to find out what is wrong, and it may or may not turn into a confirmed bug that causes code changes.

• Try to keep the list of open reports as short as possible, and also the list of confirmed, but unfixed bugs. Long lists are de-moralising, and also take effort to pick the next thing to pay attention to. This is all waste.

• It's good to have a public tracker of issues and bugs. It can be as easy as a static web page you maintain manually, or it can be something automated, such as the Debian BTS, or Bugzilla, or any of the myriad other options.

• Automated trackers tend to enforce some process. Some of them make this rather heavy, others keep it quite lightweight. For small projects, lightweight is a much better option. Only add a more heavyweight process after it's already clearly needed.

• You should probably make it easy to report issues. Some people prefer to make it less easy in order to avoid too many issues being reported for trivial things, but my preference is to keep the threshold as low as possible.

• Whatever you do, treat those who report issues with kindness. Be gracious. Be friendly. Be open to the possibility that you've made a mistake.