Handling bug reports explicitly

(Thoughts after a recent mail conversation...)

As a project maintainer, it's helpful to all concerned, but most especially you, if you are as explicit as possible when handling bug reports. In other words, explain to the reporter exactly what you did to fix the problem they reported, and why you did it. (This might be as simple as saying you applied a patch written by the reporter, or showing the patch you wrote and applied, but usually that's not enough.) If you did nothing, explain why. If the report was made by email to a list, then make sure you CC the list with your explanation. If the report was via a bug-reporting facility, then make sure that your explanation goes into the facility.

This helps you because:

• It provides a historical record that will help you remember later what you did and why, and allow others to go back and find that information.
• It encourages your good bug reporters to make future reports, because they can see that their reports make a difference.
• It will help your bad bug reporters make better reports in the future.
• Perhaps most importantly... You'll always make mistakes (misunderstand the report, make the wrong fix, etc.): if you let as many people as possible (the reporter, readers of the mailing list to which the bug report was written, followers of traffic on the bug reporting facility) know as precisely as possible what you did, then you give them all a chance to spot your mistake. I've had (far too) many of my mistakes spotted by others by explicitly explaining what I've done. (People could always find out what you did by hunting down diffs in a source repository, or a tarball, or whatever, but the effort involved means that many people won't do that.)

It helps others because:

• The reporter of the bug knows how their problem got fixed.
• If you are an upstream package maintainer, it will help downstream maintainers know what you did and why.
• If you are a downstream package maintainer, it will help the upstream maintainer know what you did and why, which will help them decide whether to integrate your downstream changes upstream. 

(2012-03-25: Edit to fix a minor wording problem.)