David Baron's Weblog

The most important field in a bug report: the summary

Monday, 2010-04-26, 14:28 -0700

I think the most important field in a bug report is the summary. (The detailed description comes in a close second, though.)

The summary of a bug is used as the first step in determining:

and it should evolve over time (as more information is learned about the bug) to meet these two purposes. Determining how important a bug is and whether two bugs are the same are generally done multiple times over the lifetime of a bug report.

For both of these purposes, there are two things that should be part of the summary: first, what goes wrong, and second, once it's known, when (under what conditions) it goes wrong.

Making the summary good for determining whether two bugs are the same requires one addition: including extra keywords in some cases to make the summary more searchable. For example, if something could be called by two names, it's often to include both in the summary (sometimes with the second in parentheses after the first).

Some examples of good bug summaries:

Next in this series, hopefully: a blog post about what makes a good commit message (hint: it's different from a good bug summary).