bug-tracking - 票证/错误格式有多重要？

Question

格式化错误报告有多重要？它应该包含什么？

我通常在错误报告中看到以下部分：

重现步骤
我所看到的
我必须看到的
解释

格式化错误报告的最佳解决方案是什么以及它应该包含什么？

score 6 · Accepted Answer

最重要的是跟踪问题。如果它被跟踪，它就不会被遗忘。

格式是锦上添花。

那说：

重现步骤
硬件运行
操作系统版本、软件版本
它正在做什么与它应该做什么

这些很重要。

此外，门票永远不应该被删除，只需解释一下即可。输入工单的信息永远不应该被删除，只是被标记为错误的。这一切都是为了跟踪问题的生命周期。

score 3 · Accepted Answer

错误报告格式指南

为了清楚地跟踪我们在 Rawr 中有哪些错误和功能请求，我们要求用户在将错误发布到问题跟踪器时提供以下信息。

标题- 这应该概述错误所在的类别（模型，如果它是特定于模型的，或者高级功能，如比较、优化器等），并简要描述问题。如果不确定类别，只需将其关闭，我们将根据需要进行调整。
描述- 这应该不再是一个段落，它应该快速概述什么是坏的/不工作的。
重现步骤- 听起来确实如此，这些是重现相关错误的步骤。您应该从启动应用程序开始。
版本号/附加信息- 您正在运行的 Rawr 版本、您的操作系统、堆栈跟踪和错误消息。请注意，大型错误消息（例如在 Rawr 崩溃期间通常产生的错误消息）应保存到 error.txt 文件并附加到问题中，而不是发布到描述中。这为打算解决该问题的开发人员提供了更清晰的格式和更少的滚动。
详细信息- 在页面右侧，请填写类型（问题）、发布（版本号）和组件（如果有）。
附件- 附上重现问题的角色文件。

例子

标题： [项目编辑器] 项目编辑崩溃
描述：当我编辑 helm 项目时，Rawr 崩溃。
重现步骤：

启动 Rawr
工具 > 编辑项目
选择血牙面具
将敏捷值从 112 更改为 113
单击“确定”按钮
观察 Rawr 崩溃

score 2 · Accepted Answer

归根结底，格式的重点是确保人们始终如一地包含足够的信息来重现或调试问题。如果您不强制执行某种格式，人们会使用任何想到的格式。对于对软件开发过程有很好理解的组织良好的人，他们可能会自己包含所有相关信息。

另一方面，在许多情况下，您会收到来自整个组织甚至直接来自用户的错误报告。或者就此而言，有些人可能只是匆忙而没有某种标准格式作为指导，您可能会收到诸如“应用程序无法正常工作”之类的错误报告等。在一天结束时，不管foramt，您只需要最少量的必要信息来确定所报告的确切问题是什么（它在哪里，什么时候发生，如何重现它）并使您能够调试它。

score 2 · Accepted Answer

实际上，我认为最重要的是确保您使用的术语易于搜索。大多数重复的错误将来自使用非标准术语。

至于确切的格式，我认为这并不重要。可以以任何格式创建可怕的票证。

只要有有助于将其引导给正确的人的基本元数据（什么组件、什么平台和重要性），其他一切都只是锦上添花，文字叙述就足够了。

我认为大多数程序员都足够擅长弄清楚什么是相关的。如果我的 Web 应用程序有问题，我会报告浏览器版本，但不必提及我正在使用多少个处理器或我的确切操作系统版本是什么。如果我可以提炼它们，我会提到重现的步骤，等等。

score 1 · Accepted Answer

我见过的最好的书面观点之一是 Simon Tatham（PuTTY 的作者）： http: //www.chiark.greenend.org.uk/~sgtatham/bugs.html。

如何有效地报告错误

作者：Simon Tatham，专业的自由软件程序员

介绍

任何编写过供公众使用的软件的人都可能至少收到过一份糟糕的错误报告。什么都不说的报告（“它不起作用！”）；毫无意义的报告；没有提供足够信息的报告；提供错误信息的报告。报告最终是用户错误的问题；报告原来是其他人的程序错误的问题；报告最终是网络故障的问题。

技术支持被视为一项可怕的工作是有原因的，原因是糟糕的错误报告。然而，并不是所有的错误报告都令人不快：我维护自由软件，当我不谋生时，有时我会收到非常清晰、有用、信息丰富的错误报告。

在这篇文章中，我将尝试清楚地说明什么是好的错误报告。理想情况下，我希望世界上的每个人在向任何人报告任何错误之前都阅读这篇文章。当然，我希望向我报告错误的每个人都阅读它。

简而言之，错误报告的目的是使程序员能够看到程序在他们面前失败。您可以亲自向他们展示，也可以向他们提供有关如何使其失败的详细说明。如果他们可以让它失败，他们将尝试收集额外的信息，直到他们知道原因。如果他们不能让它失败，他们将不得不要求您为他们收集这些信息。

在错误报告中，尽量清楚地说明什么是实际事实（“我在电脑前，这件事发生了”）以及什么是推测（“我认为问题可能是这个”）。如果您愿意，请忽略猜测，但不要忽略事实。

当您报告错误时，您这样做是因为您希望修复错误。对程序员发誓或故意无助是没有意义的：这可能是他们的错和你的问题，你可能对他们生气是对的，但如果你通过提供所有信息来帮助他们，这个错误会更快得到修复他们需要。还要记住，如果程序是免费的，那么作者提供它是出于好意，所以如果有太多人对他们粗鲁，他们可能会停止友好。

“这行不通。”

给程序员一些基本智能的功劳：如果程序真的根本不起作用，他们可能会注意到。既然他们没有注意到，那肯定对他们有用。因此，要么你做的事情与他们不同，要么你的环境与他们不同。他们需要信息；提供此信息是错误报告的目的。更多信息几乎总是比更少信息好。

许多程序，尤其是免费程序，都会发布他们的已知错误列表。如果您可以找到已知错误的列表，则值得阅读它以查看您刚刚发现的错误是否已知。如果它已经知道，则可能不值得再次报告，但如果您认为您的信息比错误列表中的报告更多，您可能还是想联系程序员。如果您可以向他们提供他们还没有的信息，他们可能能够更轻松地修复错误。

这篇文章充满了指导方针。它们都不是绝对规则。特定的程序员有他们喜欢报告错误的特定方式。如果该程序带有自己的一套错误报告指南，请阅读它们。如果程序随附的指南与本文中的指南相矛盾，请遵循程序随附的指南！

如果您没有报告错误而只是寻求使用该程序的帮助，您应该说明您已经在哪里寻找问题的答案。（“我查看了第 4 章和第 5.2 节，但找不到任何告诉我这是否可能的信息。”）这将使程序员知道人们期望在哪里找到答案，因此他们可以使文档更易于使用.

“给我看看。”

报告错误的最佳方法之一是将其展示给程序员。让他们站在你的电脑前，启动他们的软件，并演示出问题的地方。让他们观察你启动机器，观察你运行软件，观察你如何与软件交互，观察软件如何响应你的输入。

他们对软件了如指掌。他们知道自己信任哪些部件，也知道哪些部件可能出现故障。他们凭直觉知道要注意什么。当软件做一些明显错误的事情时，他们很可能早就注意到了一些微妙的错误，这可能会给他们一个线索。他们可以观察计算机在测试运行期间所做的一切，并且可以自己挑选出重要的部分。

这可能还不够。他们可能会决定他们需要更多信息，并要求您再次向他们展示相同的信息。他们可能会要求您与他们讨论整个过程，以便他们可以根据需要多次为自己重现错误。他们可能会尝试改变程序几次，以查看问题是仅发生在一个案例中还是在一系列相关案例中。如果你不走运，他们可能需要用一套开发工具坐下来几个小时，然后真正开始调查。但最重要的是让程序员在计算机出错时查看计算机。一旦他们看到问题正在发生，他们通常可以从那里着手并开始尝试修复它。

“告诉我如何展示自己。”

这是互联网时代。这是全球通信的时代。在这个时代，我只需按一下按钮就可以将我的软件发送给俄罗斯的某人，他也可以很容易地向我发送有关它的评论。但是如果他对我的程序有问题，他不能让我在它失败时站在它前面。可以时“给我看”很好，但通常不能。

如果您必须向不能亲自到场的程序员报告错误，那么练习的目的是让他们重现问题。您希望程序员运行他们自己的程序副本，对其执行相同的操作，并以相同的方式使其失败。当他们能看到眼前发生的问题时，他们就可以处理它。

所以告诉他们你做了什么。如果是图形程序，请告诉他们您按了哪些按钮以及按的顺序。如果是您通过键入命令运行的程序，请准确地向他们显示您键入的命令。只要有可能，您应该提供会话的逐字记录，显示您键入的命令以及计算机输出的响应内容。

给程序员你能想到的所有输入。如果程序从文件中读取，您可能需要发送该文件的副本。如果程序通过网络与另一台计算机通信，您可能无法发送该计算机的副本，但您至少可以说出它是什么类型的计算机，以及（如果可以的话）上面运行的是什么软件。

“对我有用。所以出了什么问题？”

如果你给程序员一长串输入和动作，他们启动了自己的程序副本并且没有出错，那么你没有给他们足够的信息。可能故障不会出现在每台计算机上；您的系统和他们的系统可能在某些方面有所不同。可能你误解了程序应该做什么，并且你们都在看完全相同的显示，但你认为这是错误的，他们知道这是正确的。

所以还要描述发生了什么。准确地告诉他们你看到了什么。告诉他们为什么你认为你看到的东西是错的；更好的是，准确地告诉他们您希望看到的内容。如果您说“然后它出错了”，那么您遗漏了一些非常重要的信息。

如果您看到错误消息，请仔细而准确地告诉程序员它们是什么。他们很重要！在这个阶段，程序员并没有试图解决问题：他们只是试图找到它。他们需要知道出了什么问题，而这些错误消息是计算机告诉您的最大努力。如果您没有其他简单的方法来记住错误，请将它们写下来，但是除非您还可以报告错误消息是什么，否则不值得报告程序产生了错误。

特别是，如果错误消息中有数字，请让程序员拥有这些数字。仅仅因为你看不到它们的任何意义并不意味着没有任何意义。数字包含了程序员可以阅读的各种信息，并且很可能包含重要的线索。错误消息中有数字是因为计算机太混乱而无法用文字报告错误，但它正在尽最大努力以某种方式将重要信息提供给您。

在这个阶段，程序员正在有效地做侦探工作。他们不知道发生了什么，也无法靠得足够近自己亲眼目睹，因此他们正在寻找可能泄露事件的线索。错误信息、难以理解的数字串，甚至无法解释的延误都与犯罪现场的指纹一样重要。保留它们！

如果您使用的是 Unix，则该程序可能已生成核心转储。核心转储是一个特别好的线索来源，所以不要把它们扔掉。另一方面，大多数程序员不喜欢在没有警告的情况下通过电子邮件接收巨大的核心文件，所以在给任何人邮寄之前先问清楚。此外，请注意核心文件包含程序完整状态的记录：任何涉及的“秘密”（可能程序正在处理个人消息，或处理机密数据）都可能包含在核心文件中。

“那我试着……”

当出现错误或错误时，您可能会做很多事情。他们中的许多人使问题变得更糟。我在学校的一个朋友错误地删除了她所有的 Word 文档，在寻求专家帮助之前，她尝试重新安装 Word，然后尝试运行 Defrag。这些都没有帮助恢复她的文件，并且在他们之间他们对她的磁盘进行了加扰，以至于世界上没有任何 Undelete 程序能够恢复任何东西。如果她只是不理会它，她可能还有机会。

像这样的用户就像一只被逼到墙角的猫鼬：背对着墙，看到死神盯着它的脸，它疯狂地攻击，因为做某事总比什么都不做要好。这不能很好地适应计算机产生的问题类型。

与其做一只猫鼬，不如做一只羚羊。当羚羊遇到意想不到或可怕的事情时，它会僵住。它保持绝对静止并尽量不吸引任何注意力，而它会停下来思考并找出最好的办法。（如果羚羊有技术支持热线，它会在此时给它打电话。）然后，一旦它决定了最安全的做法是什么，它就会去做。

当出现问题时，立即停止做任何事情。根本不要触摸任何按钮。看着屏幕，注意所有不寻常的事情，然后记住或写下来。然后也许开始小心地按“确定”或“取消”，以最安全的为准。试着发展一种反射反应——如果电脑做了任何意想不到的事情，就停下来。

如果您设法摆脱问题，无论是通过关闭受影响的程序还是通过重新启动计算机，最好的办法是尝试让它再次发生。程序员喜欢可以多次重现的问题。快乐的程序员可以更快、更有效地修复错误。

“我认为快子调制一定是被错误地极化了。”

不只是非程序员会产生糟糕的错误报告。我见过的一些最糟糕的错误报告来自程序员，甚至来自优秀的程序员。

我曾经和另一个程序员一起工作过，他一直在自己的代码中发现错误并试图修复它们。每隔一段时间，他就会遇到一个他无法解决的错误，他会叫我过来帮忙。“怎么了？” 我会问。他会告诉我他目前对需要解决的问题的看法。

当他目前的意见正确时，这很好。这意味着他已经完成了一半的工作，我们能够一起完成工作。这是有效和有用的。

但很多时候他是错的。我们会工作一段时间试图弄清楚为什么程序的某些特定部分会产生不正确的数据，最终我们会发现不是这样，我们已经研究了半个小时的完美代码，并且实际问题出在其他地方。

我敢肯定他不会对医生那样做。“医生，我需要一张Hydroyoyodyne的处方。” 人们知道不要对医生这么说：你描述症状、实际的不适、疼痛、皮疹和发烧，然后让医生诊断问题所在以及如何处理。否则，医生会认为你是一个疑病症或疯子，这是完全正确的。

程序员也是一样。提供您自己的诊断有时可能会有所帮助，但请务必说明症状。诊断是可选的附加项，而不是给出症状的替代方案。同样，发送对代码的修改以解决问题是对错误报告的有用补充，但不足以替代错误报告。

如果程序员要求您提供额外信息，请不要编造！有人向我报告了一个错误，我让他尝试一个我知道不会起作用的命令。我让他尝试的原因是我想知道它会给出两种不同的错误信息中的哪一种。知道返回的错误消息将提供重要线索。但他实际上并没有尝试过——他只是给我回了邮件说“不，那行不通”。我花了一些时间说服他真正尝试一下。

用你的智慧来帮助程序员很好。即使你的推论是错误的，程序员也应该感激你至少试图让他们的生活更轻松。但也要报告症状，否则你可能会让他们的生活变得更加困难。

“这很有趣，它刚刚做到了。”

对任何程序员说“间歇性故障”，然后看着他们的脸掉下来。简单的问题是执行简单的操作序列会导致故障发生的问题。然后，程序员可以在密切观察的测试条件下重复这些操作，并详细观察发生的情况。太多的问题根本就不是这样工作的：会有程序每周失败一次，或者在蓝月亮中失败一次，或者当你在程序员面前尝试它们时永远不会失败，但当你有最后期限时总是失败向上。

大多数间歇性故障并不是真正的间歇性。他们中的大多数在某个地方都有一些逻辑。有些可能在机器内存不足时发生，有些可能在另一个程序尝试在错误的时刻修改关键文件时发生，有些可能仅在每小时的前半段发生！（我实际上见过其中之一。）

此外，如果您可以重现错误但程序员不能重现，则很可能是他们的计算机和您的计算机在某些方面有所不同，而这种差异导致了问题。我曾经有一个程序，它的窗口在屏幕左上角蜷缩成一个小球，然后坐在那里闷闷不乐。但它只在 800x600 屏幕上做到了；在我的 1024x768 显示器上很好。

程序员会想知道你能找到的关于这个问题的任何事情。也许在另一台机器上试试。尝试两次或三次，看看失败的频率。如果它在你做严肃的工作时出错，但在你试图展示它的时候却没有，可能是运行时间长或文件太大导致它崩溃。尝试尽可能多地记住当它倒下时你对它所做的事情的详细信息，如果你看到任何模式，请提及它们。你能提供的任何东西都必须是一些帮助。即使它只是概率性的（例如“当 Emacs 运行时它往往会更频繁地崩溃”），它可能无法提供问题原因的直接线索，但它可能有助于程序员重现它。

最重要的是，程序员需要确定他们处理的是真正的间歇性故障还是特定于机器的故障。他们会想知道有关您的计算机的许多详细信息，以便他们可以弄清楚它与他们的计算机有何不同。许多这些细节将取决于特定的程序，但您绝对应该准备好提供的一件事是版本号。程序本身的版本号，操作系统的版本号，以及可能涉及问题的任何其他程序的版本号。“所以我将磁盘加载到我的 Windows 上……”

在错误报告中写清楚是必不可少的。如果程序员不能说出你的意思，你还不如什么都没说。

我收到来自世界各地的错误报告。他们中的许多人来自非英语为母语的人，其中很多人为他们糟糕的英语道歉。一般来说，为他们的英语糟糕而道歉的错误报告实际上非常清晰和有用。所有最不明确的报告都来自以英语为母语的人，他们认为我会理解他们，即使他们不努力清楚或准确。

请明确点。如果您可以用两种不同的方式做同样的事情，请说明您使用的是哪一种。“我选择了加载”可能意味着“我点击了加载”或“我按下了 Alt-L”。说你做了什么。有时这很重要。
详细一点。提供更多而不是更少的信息。如果你说的太多，程序员可以忽略其中的一些。如果你说的太少，他们必须回来问更多的问题。我收到的一个错误报告是一句话；每次我问更多的信息，记者都会再回复一句。我花了几个星期才获得大量有用的信息，因为它一次只出现一个简短的句子。
小心代词。当不清楚它们的意思时，不要使用像“它”这样的词，或者像“窗户”这样的引用。考虑一下：“我启动了 FooApp。它打开了一个警告窗口。我试图关闭它，但它崩溃了。” 目前尚不清楚用户试图关闭什么。他们是试图关闭警告窗口，还是关闭整个 FooApp？它有所作为。相反，您可以说“我启动了 FooApp，它显示了一个警告窗口。我试图关闭警告窗口，结果 FooApp 崩溃了。” 这更长，更重复，但也更清晰，更不容易误解。
读你写的。把报告读给自己听，看看你是否认为它很清楚。如果您列出了一系列应该导致失败的操作，请尝试自己遵循它们，看看您是否错过了一个步骤。

概括

错误报告的第一个目的是让程序员亲眼看到失败。如果你不能和他们一起让它在他们面前失败，给他们详细的指示，让他们自己让它失败。
如果第一个目标没有成功，而程序员自己也看不到它失败了，那么错误报告的第二个目标就是描述哪里出了问题。详细描述一切。陈述你看到的，也陈述你期望看到的。写下错误消息，尤其是如果它们有数字。
当您的计算机出现意外情况时，请冻结。在你冷静之前什么都不做，不要做任何你认为可能有危险的事情。
如果您认为可以，请务必尝试自己诊断故障，但如果您这样做了，您仍然应该报告症状。
如果程序员需要，请准备好提供额外信息。如果他们不需要它，他们就不会要求它。他们不是故意尴尬。让版本号触手可及，因为它们可能会被需要。
写清楚。说出你的意思，并确保它不会被误解。
最重要的是，要精确。程序员喜欢精确。

免责声明：我从未真正见过猫鼬或羚羊。我的动物学可能不准确。

$Id: bugs.html 8168 2008-09-08 18:03:28Z simon $

score 0 · Accepted Answer

同样重要的是了解世卫组织实际上可以查看和填充诸如“复制步骤”之类的问题字段。问错人，他们会给你垃圾数据。

这里有一些有用的建议