pcb-rnd knowledge pool

Abstract: Optional: tips on how to write the most useful, self-contained bugreports. Best practices on writing bugreports and rationale how these tricks help fixing the bugs.

  I have to deal with like 20..40 different issues and topics related to pcb-rnd daily, while most users and bug reporters need to deal with only 1 or 2 for a few days, while they are reporting the bug. From the reporter side this means a set of random hints and emails easily make up a coherent story, even using just the reporter's own memory.

From my seat, it is different, tracking dozens of parallel stories, connecting random pieces of the puzzle from different mails and chatlogs is not that simple.

One way to make the developer's life easier is to try to produce self contained bugreports. It's obviously optional, but definitely would help the project.

A good self contained bugreport has the following properties, regardless of the communication channel the bug is reported on:

1. it describes one single bug, does not bundle a bunch if similar looking but otherwise potentially independent problems. (It's easier to figure 2 reports are duplicate or they got fixed by fixing the same root cause than trying to follow days long threads revolving around 6 different issues.)

2. most of the time I will want to reproduce the bug, if for nothing else, for checking whether my fix really fixed it; for this, I need a test case. If you have a test case already and you don't include it in the report, I will have to spend my time reproducing it. Time spent on producing something that already existed, instead of the same time spent on fixing more bugs.

3. the perfect test case is as small as it can get, still reproducing the one problem being reported

4. a good bugreport can be fully understood without following any reference to previous mailing or having to remember anything from hours or days ago. A good bugreport allows me to fix a bug even if I don't have anything else just the sources and the report.

5. a good bugreport is specific, not generic. When the reporter says "vias break" it often means "vias work in 99.999% of the cases but the reporter found an exotic corner case where one-of-his-1000-vias broke". I need to see one specific broken case; it's then very easy for me to figure whether it's a generic problem or a corner case. The other way around is much more expensive: trying to figure what the special corner case could be that happened to break.

6. generic approach: we do not doubt you've found a bug. The goal is not to prove you have found a bug, or what you are seeing is really a bug. 95% of the times it is a bug, only 5% of the times we'd say it's not. The goal is to produce a report that is the most efficient input for working out the fix.

7. the bugreport always should contain "what happened" vs. "what I was expecting instead". Even for the most trivial cases. Rationale: the reporter is in a different context than the programmer who will deal with the report. What's trivial , knowing all the context the reporter knew after spending hours in that context, is very different from what's trivial for fresh eyes.

Self contained bugreports are also very important because we can't always fix things right away, which means a report may be sitting for days or even weeks in the queue. Even the original reporter won't remember all details next month.