Five Principles of Bug Tracking

The following text is a partial translation of the original English article, performed by ChatGPT (gpt-3.5-turbo) and this Jekyll plugin:

一个远程工作团队需要比坐在同一个办公室的团队更强的纪律。首先,我指的是沟通纪律。在Zerocracy上,我们过去五年一直远程开发软件。我们通过工单系统(如GitHub、JIRA、Trac、Basecamp等)严格管理任务,并且不鼓励任何非正式的沟通方式,如Skype、HipChat、电子邮件或电话。对于我们来说,每个工单都是一个独立的任务,有着自己的生命周期、参与者和目标。在这些年里,我们学到了一些经验,我想分享给大家。如果你也与团队远程工作,你可能会觉得它们很有用。

每张票(也称为“错误”)都是两个人之间的链接:问题的指定者和问题的解决者。如果是一个错误,我会报告它,你来解决。如果是一个问题,我会请求解释,你来解释。如果是一个任务,我会命令你去做,你来完成。无论如何,都有两个主要角色。无论在解决票务的过程中涉及多少人,只有这两个角色才具有正式的职责。

报告票务者的责任是维护问题。当我报告一个错误时,我必须坚持它的存在-这是我的工作。其他人可能告诉我我错了,错误并不存在。他们可能告诉我他们无法复现此错误。他们可能说我对任务的描述太模糊,没有人理解。可能会有很多这样的问题。我的工作是尽力做到使票务保持活跃。显然,如果错误无法复现,我将被迫关闭票务。然而,在票务关闭之前,我是它的守护天使。

另一方面,解决票务者的责任是维护解决方案。当一个票务指派给我并且我需要解决它时,我的工作是说服报告者我的解决方案足够好。他可能告诉我我的解决方案不够好,不够高效或者不完整。我的工作是坚持我是对的,他是错的。当然,以一种合理的方式。为了创建一个被接受为足够好的解决方案,我必须首先理解问题,研究所有可能的选择,并提出最优雅的实施方案。但所有这些都是次要的。我将始终专注于如何说服报告者。我将永远记住我的主要目标是关闭票务

我在这里的观点是,无论在票务讨论中涉及多少人,请始终记住正在发生的事情-一个人正在向另一个人销售他的解决方案。其他人都只是帮助或干扰(见下文)。

请记住,一个工单不是聊天的地方。你不是去聊天的,你是去“解决问题”的。当工单分配给你时,专注于尽快解决它(还记得“一直在关闭”吗?)。

同时,要记住,你越早解决工单,对项目而言就越好。长期存在的工单是一种管理上的“噩梦”。很难跟踪和控制它们。很难理解发生了什么。你见过那些开源项目中的两年前的工单吗?它们有数百条评论,但没有交付成果。这是项目经理和工单参与者的错误。每个工单都应该简短而专注——1)一个问题,2)一个细化问题,3)一个简短的解释,4)一个解决方案,5)关闭,谢谢大家。这是一个理想的情况。

一旦你意识到你的工单正在变成长时间的讨论,尝试更快地关闭它。如果报告人不喜欢我的解决方案,我该如何关闭它?找到一个能满足报告人并允许你关闭工单的临时解决方案。在你的代码中使用“TODO”或者一些权宜之计——它们都比长时间悬而未决的工单好。

一旦你看到解决方案已经提供,并且足够关闭工单,请要求报告人关闭它。明确要求报告人这样做,不要拐弯抹角地说“看起来这个解决方案可能会被接受,如果你不介意的话。”明确表达你关闭工单并继续工作的意图。试试这样说:“@jeff,请关闭工单,如果你没有其他问题。”

每次您提出一个错误并创建一个新的工单,都会消耗项目资源。每个错误报告都意味着在项目上花费了金钱:1)用于您花费时间找到问题并报告的工资;2)用于项目经理与工单一起工作并找到谁来修复问题的时间;3)用于工单解决者试图理解您的报告并提供解决方案的时间;还有4)用于参与讨论的其他人的时间。

如果您在没有解决问题的情况下关闭工单,那么这笔钱就白白浪费了。一旦工单启动,就没有回头的余地。我们不能只说,“算了,忽略它;它不再重要了。”您的工单已经消耗了项目的时间和预算资源,为了将它们变成有用的东西,您必须确保至少提供某种解决方案。

它可以是一个临时解决方案。可以是项目文档中的一行更改。可以是代码中的TODO标记,表示“我们意识到问题但不会修复它,因为我们懒得动手。”任何解决方案都可以,但不能是没有任何解决方案。

从另一个角度看待这个问题。当您启动那个工单时,您心中有一个想法。产品有些地方不对劲。这就是为什么您报告了一个错误。如果您关闭工单而没有任何人甚至触碰代码的那个地方,几天或几年后,其他人将会有同样的担忧。然后项目将不得不再次为类似的工单或讨论同样的问题支付费用。即使您相信您在代码中找到的问题并不是真正的问题,请要求一个工单解决者在源代码中记录下来,以防止将来再次发生类似的混淆。

每次您向工单发布消息时,请寄给某人。否则,如果您只是想表达自己的意见,您的评论就变成了沟通中的“噪音”。请记住,工单是两个人之间的对话—其中一个人报告了一个问题,另一个人正在努力修复它。像“我们尝试另一种方法怎么样”或“我记得我以前遇到过类似的问题”这样的评论非常令人讨厌和分散注意力。坦率地说,没有人真正需要或关心“意见”。工单中我们需要的只是解决方案。

如果您认为工单应该关闭,因为已经提出的解决方案足够好,请将您的评论寄给工单的报告人。并以“@jeff,我认为你已经得到的解决方案已经足够好,因为…”开始。这样,您将帮助被指派的人关闭工单并继续工作。

如果您认为解决方案是错误的,请将您的评论寄给工单的被指派人,以“@jeff,我认为你的解决方案不够好,因为…”开始。这样,您将帮助工单的报告人保持工单的开放状态,直到出现适当的解决方案。

再次强调,不要用普遍的意见污染空气。相反,要非常具体并且要站在某一方面—您可以喜欢解决方案并希望关闭工单,或者您不喜欢它并希望保持工单的开放状态。两者之间的一切只会使情况更加复杂,并且对项目毫无帮助。

我认为这是显而易见的,但我还是要强调一下:每个 bug 都必须可以重现。每次你报告一个 bug,你都应该解释产品究竟出了什么问题。是的,你的工作就是证明软件不按照预期工作,或者文档不完善,或者不满足需求等等。

每个 bug 报告都应该遵循同样简单的公式:“这是我们现在有的,这是我们应该有的,所以请修复它。”每个工单,无论是 bug、任务、问题还是建议,都应该按照这种方式进行格式化。通过提交工单,你正在要求项目从 A 点移动到 B 点。A 点存在问题,对于我们所有人来说,到达 B 点会更好。所以你必须解释这些 A 点和 B 点在哪里。如果你能解释如何到达那里——如何重现问题以及如何修复问题,那将是非常理想的。

即使你有一个问题,你也应该遵循这种格式。如果你有一个问题,这意味着项目文档对你来说不够详细,无法找到答案。这是有问题的。你应该要求修复。所以,与其报告“我应该如何使用 X 类?”,不如说一些类似“当前的文档不完整,没有解释我应该如何使用 X 类,请修复”。

如果你无法解释如何到达那里,在工单中说明:“我看到这个类不按照预期工作,但我不知道如何重现问题和如何修复它。”这将给每个人一个明确的信息,即你意识到你的 bug 报告不完美。解决者的第一步将是细化问题并找到重现问题的方法。如果找不到这样的副本,显然你的 bug 将被迫关闭。

让我再次强调:每个工单都将项目从存在问题的 A 点拖拽到已修复的 B 点。作为一个工单报告者,你的工作就是画出那条线——清晰明确地。

Translated by ChatGPT gpt-3.5-turbo/42 on 2023-11-28 at 14:44

sixnines availability badge   GitHub stars