前言

此翻译参考了网络中现有的中文翻译，在此基础上做了些语义调整，同时在原先中文的基础上增加了部分新增的英文内容。

原文使用的是 Bugzilla 这个 Bug 追踪工具，你可以将其代替成你所使用的缺陷管理软件或系统。

为什么你要读这份指南

简单地说，如果你报告 Bug 越有效, 工程师完全修复它的可能性就越大。
这份 Bug 写作指南是针对新手在书写有效的 Bug 报告方面进行指导的常规指南，并非每个建议都正好适用于你的软件项目。

如何写一份有用的 Bug 报告

有用的 Bug 报告是用于正确修复 Bug 的。因此一份有用的 Bug 报告通常的有两个特征：

1. 可复现：如果工程师不能复现或最终证明这一 Bug 存在,工程师或许会将它标记为 “我这没问题（WORKSFORME）”或 ”无效反馈（INVALID ）“，并且继续进行下一个 Bug 的修复工作。任何你能提供的详尽描述将为工程师修复 Bug 提供帮助。
2. 详细精确：如果工程师能越早隔离、定位问题，就越可能方便地修复。（如果程序员或测试人员不得不像破译密码一般去寻找跟踪分析 Bug，那么他们将花费比修复或测试问题更多的时间去诅咒 Bug 提交人。）

让我们举一个例子：你正在测试的应用程序是一个网络浏览器，在访问 foo.com 网站时崩溃了，因此你想写一个 Bug 报告:

• 糟糕的 Bug 报告：“我的浏览器崩溃了。我正在访问 foo.com。我和比尔-盖茨打高尔夫，所以你最好解决这个问题，否则我就向他报告你。顺便说一下,你的 “返回 “图标看起来像一只被压扁的啮齿动物。丑陋极了。还有我的祖母的主页看上去外观也不正确，或者，它们全被搞乱了。祝好运。”
• 有用的 Bug 报告：“我每次进入www.foo.com，在Windows 2000系统上使用2002-02-25的版本时都会崩溃。我还重启了Linux，并使用2002-02-24的Linux版本再现了这个问题。我发现每次崩溃都发生在绘制这个页面位于上端的 Foo 横幅的时候。我分析了页面，发现除非你删除 ” border =0″属性，否则下列图片链接将导致应用程序崩溃 ：”

如何在 Bugzilla 中输入你有用的 Bug 报告

在你输入你发现的 Bug 前，应使用 Bugzilla 查询页检查是否你发现的是已知并被报告的 Bug。（如果你发现的 Bug 同第 37 条已经知道的结果相同，你报告的话，就可能骚扰工程师，从而影响工程师修复 Bug 的效率。）

下一步,确认你发现的 Bug 是在最新的版本中所发生的。（工程师更倾向于对那些他们正在编写的代码中的严重问题感兴趣，而不是对以前那些废弃代码中数以百计的 Bug 进行修复。）

如果你已经在当前版本中发现了一个新的 Bug，请在 Bugzilla 中报告：

1. 从你的 Bugzilla 主页中,选择“Enter a new bug”。
2. 选择你发现 Bug 的产品。
3. 输入你的电子邮件地址、密码，然后按“Login”按钮。（如果你遗忘或还没有得到密码,让密码正文框空白，并且按 ” E-mail me a password “按钮，不久你将收到包含你的密码的电子邮件。）

现在，填写那张出现的表格。以下说明表格中的所有含义：

你在哪儿发现了 Bug？

• 产品：在哪一个产品中你发现了 Bug？
  你在上一页已选择，所以你不能在这编辑
• 版本：在产品的哪一个版本中你找到了 Bug？
  （如果有的话）
• 产品单元：在产品的哪一个单元中存在 Bug？
  Bugzilla 在你输入一个 Bug 时，要求你必须选择一个产品单元。（如果你无法确定所列产品单元的意思，单击产品单元链接，那将链接到对每个产品单元的详细描述，这会帮助你作出最好选择。）
• OS：在哪一个操作系统（OS）中你找到了这个 Bug？（例如 Linux、Windows 2000、Mac OS 9。）
  如果你知道这个 Bug 会发生在所有 OS 中，请选择“All”，否则请选择相应的你发现 Bug 的 OS，如果列表中没有出现你的 OS，请选择“Other”。

这个 Bug 有多重要？

• 严重性：这个 Bug 的破坏性有多大？
  这项值默认为“普通（normal）”。（要为一个特定的 Bug 界定最适当的严重性，单击严重性链接，你会看到每个严重程度的描述。）

谁将跟踪解决 Bug？

• 指定给：哪一个工程师将负责修复这个 Bug？
  在你提交 Bug 报告后，Bugzilla 将自动把 Bug 分配给默认工程师；填写正文框将允许你用手工方式把它分配给其他工程师。（要查看每个产品单元的默认工程师列表,请单击产品单元链接。）
• Cc：还有哪些人将收到这个 Bug 修复更新的电子邮件?
  列出其他需要通过电子邮件收到这个 Bug 修复更新的人的完整的电子邮件地址。您可以输入任意多的电子邮件地址，用空格或逗号隔开，只要这些人有Bugzilla帐户。

关于这个Bug你还能告诉工程师什么？

• 摘要：你如何用大约60个或更少的字符来描述这个错误？
  一个好的摘要应该能快速而独特地识别一个错误报告。否则，工程师无法通过摘要来有意义地识别你的bug，而且在浏览10页的bug列表时，往往不会注意到你的bug报告。

一个有用的摘要可能是 “PCMCIA安装在Tosh Tecra 780DVD w/ 3c589C上失败”。”软件失败 “或 “安装问题 “将是不好的摘要的例子。

• 描述：

请在这个领域提供一个详细的问题报告。你的错误的接收者很可能希望得到以下信息：
概括描述：更详细地扩展总结。
在NSGetFactory中拖动选择任何页面都会使Mac的构建崩溃
Bug复现的步骤：最小化的、易于操作的、会触发错误的步骤。包括任何特殊的设置步骤。

1. 查看任何网页。(我使用了默认的样本页。 resource:/res/samples/test0.html)
2. 拖动选择该页面。(具体来说，在按住鼠标按钮的同时，将鼠标指针从浏览器内容区域的任何一点向下拖动到浏览器内容区域的底部)

目前的结果：执行上述步骤后，应用程序做了什么。
该应用程序崩溃了。下面是MacsBug的堆栈爬行。
期望的结果：如果不存在这个错误，应用程序应该做什么。

窗口应向下滚动。滚动的内容应该被选中。
(或者，至少，应用程序不应该崩溃）。
时间及硬件平台：第一次出现这个Bug的时间及硬件平台。
在Mac OS 9.0上构建2002-03-15
其它环境及硬件平台：Bug是否出现在其他硬件平台或浏览器上。

• 也出现在
  Mozilla (2002-03-15 build on Windows NT 4.0)
• 不出现在
  Mozilla (2002-03-15 build on Red Hat Linux; feature not supported)
  Internet Explorer 5.0 (在Windows NT 4.0上运行的版本)
  Netscape Communicator 4.5 (在Mac OS 9.0上发布)

其它信息：任何其他调试信息。对应崩溃的错误：

• Win32: 如果你收到华生医生的错误( Dr. Watson error), 请注意崩溃的类型，以及应用程序崩溃的模块。(例如：apprunner.exe中的访问违规)
• Mac OS: 如果你运行的是MacsBug，请提供一个how和一个sc的结果:

*** MACSBUG STACK CRAWL OF CRASH (Mac OS)
Calling chain using A6/R1 links 
Back chain  ISA  Caller 
00000000    PPC  0BA85E74   
03AEFD80    PPC  0B742248   
03AEFD30    PPC  0B50FDDC  NSGetFactory+027FC
PowerPC unmapped memory exception at 0B512BD0 NSGetFactory+055F0

你已经完成了一篇不错的bug报告！

在确认你的输入无误后，请按“t提交（Commit）”按钮，现在你的Bug报告已经存入Bugzilla数据库。

关于写好 Bug 报告的更多信息

1. 有用的Bug报告的一般提示

使用一个明确的结构，这样你的错误报告就很容易被浏览。错误报告的用户通常需要立即访问您的错误的特定部分。如果您安装的Bugzilla支持Bugzilla帮助器，请使用它。

避免可爱，如果它需要清晰度。没有人会在凌晨3点时因为你那有趣的错误标题而发笑，因为他们不记得如何找到你的错误。

每个报告只有一个bug。完全不同的人通常会修复、验证和优先处理不同的bug。如果你在一份报告中混入了大量的bug，正确的人可能不会及时发现你的bug，或者根本不会发现。某些bug也比其他的更重要。当一个错误报告包含四个不同的问题时，不可能对其进行优先排序，这些问题的重要性各不相同。

没有一个错误是不值得报告的。除非你正在阅读源代码，否则你无法看到实际的软件错误，如空指针 – 你会看到它们的可见表现，如应用程序最终崩溃时的故障。严重的软件问题可以通过表面上微不足道的方式表现出来。无论如何要把它们归档。

2. 如何以及为什么要写好Bug总结？

你想给错误接收者留下一个好的第一印象。就像《纽约时报》的标题引导读者从几十种选择中找到相关的文章一样，你的bug摘要是否会暗示你的bug报告值得从几十种或几百种选择中阅读？

相反，像安装问题这样的模糊的bug摘要会迫使审查安装bug的人浪费时间打开你的bug来确定它是否重要。

你的bug经常会被它的摘要所搜索到。就像你用Google通过直觉搜索关键词来找到网页一样，其他人也会找到你的bug。描述性的bug摘要自然是富含关键词的，而且更容易找到。

例如，如果你搜索 “列表”、”终端 “或 “路径”，你会发现一个题为 “将图标从列表视图拖到gnome终端（gnome-terminal）不会粘贴路径 “的错误。这些搜索关键词不会发现一个题为 “拖动图标不能粘贴 “的错误。

问问自己，”有人会从这个摘要中理解我的错误吗？” 如果是这样，你已经写了一个很好的摘要。

不要写像这样的标题:

1. “无法安装” - 为什么无法安装？当你尝试安装时会发生什么？
2. “严重的性能问题” - ……当你做什么的时候会出现这些问题？
3. “返回按钮不生效” - 生效过吗？还是根本没有？

好的错误标题：

1. “如果存在Mozilla M18包，1.0升级安装失败” - 解释了问题和背景。
2. “如果在Red Hat 6.2（RPM 3）系统上启动RPM 4安装程序会崩溃” - 解释了发生的情况和背景。

（完）

参考

• Bug Writing Guidelines