# 撰写有效的 Bug 报告 * 原文：[Writing Effective Bug Reports](https://freebsdfoundation.org/our-work/journal/browser-based-edition/embedded-2/writing-effective-bug-reports/) * 作者：Tom Jones 几年前，我们深受敬重的前 FreeBSD 期刊编辑委员会成员 Kristof Provost 写过一篇关于理想 Bug 报告方式的好文章。遗憾的是，Michael W Lucas 总会在年初就用光我们每期讽刺的额度，所以为了避免“讽刺透支”，决定由我改写 Kristof 的原文，以免出现“反讽破产”。 每个系统维护者都有自己偏好的 Bug 报告与改进请求接收方式。由于 Kristof 是 FreeBSD 中 pf 开发的核心人物，他正是为期刊撰写这篇文章的理想人选。 在被要求改写原文时，Kristof 的回应是： *“我无法在完美的基础上再做改进。”* 因此，我来重述 Kristof 的原话，并给你一些入门建议，帮助你更快地整理出最重要、最棘手的 Bug。你可以在这里找到他的博文：。 ## Bug 软件项目常常让人觉得就是由 Bug 堆砌而成；开发者会说一切都是鞋油和胶带粘起来的。造成最大麻烦的问题往往最难捉摸。“深夜，当 12 个并发请求同时打到我们的测地负载均衡器上时……”并不是复杂 Bug 的罕见开头。有时问题的描述甚至是“运行 1000 小时之后……”这种令人头疼的情况。 幸运的是，并非所有 Bug 都如此。FreeBSD 在许多情况下会 panic，对用户而言可能是糟糕的一天，但对开发者而言，panic 消息可能是定位问题的重要线索。和无声的数据损坏相比，我宁愿碰到 panic。 有些 Bug 只是表面问题，比如字段显示不佳，或文档不清晰（是的，我们也认为这算 Bug！）。 无论你的 Bug 是逻辑上的不可能，还是一个拼写错误，我会给你展示一个框架，帮助你推动修复。 ## Bug 生命周期 在介绍如何写好 Bug 报告之前，先说说之后会发生什么，因为这能解释为什么你需要在最初报告时尽可能多提供信息。 在 FreeBSD 中，大多数 Bug 会通过邮件列表或 Bug 跟踪系统（[bugs.freebsd.org](https://bugs.freebsd.org/)）传播。开发者会定期阅读邮件列表，但最能引起关注的方法还是在 Bug 跟踪系统上提交工单。 新创建的 Bug 会被标记为“new”，处于新 Bug 状态。这时它只是被用户提交，还没有通知到具体的项目领域。 Bugmeister 团队会检查新提交，将其从“new”状态重新分配，并尽量设置正确的分类。开发者可以选择订阅某些类别的 Bug。相关的项目邮件列表也会收到新 Bug 的通知。另外，还会定期发送“该组关注的 Bug”摘要邮件。 Bug 可能会被 Bugmeister 或其他 FreeBSD 项目成员分配给某个开发者。 某个开发者可能决定“接手”一个 Bug，成为该问题的负责人。这通常意味着他决定修复这个 Bug 或分析它。 随后可能会有一些往返沟通，开发者会要求更多信息；如果一切顺利，开发者最终会创建代码审查（在 [reviews.freebsd.org](https://reviews.freebsd.org) 上）。代码审查可能会在 Bug 中引用，也可能只是开发者向熟悉该子系统的同行寻求反馈。 如果需要测试以确认 Bug 是否解决，这会被特别指出。 最终，待代码审查与测试完成，修复就会被提交到 FreeBSD；提交消息通常会包含 Bug 的引用，并附加自动更新。有时修复一个 Bug 需要多个补丁。 修复提交后，你（用户）就能再次无 Bug 使用软件，前提是你运行的是 CURRENT 快照。许多修复会从 CURRENT 合并到 STABLE 分支（称为 MFC）。如果 Bug 被 MFC，修复就会出现在 STABLE 分支，并包含在下一个点版本中。 从报告问题到修复的过程可能很长；有的问题 20 分钟就能解决，有的问题可能需要数月甚至数年。我见过调试超过十年才关闭的 Bug。 解决一个问题所需的时间，很大程度上取决于你报告的时机。如果你在提交刚落地后就发现 Bug，很可能当天就能修复。其他 Bug 可能更晚才出现，或只出现在某些 FreeBSD 发行版本的环境中。 修复这些 Bug 的速度，主要取决于 Bug 报告的质量以及围绕问题的持续讨论。接下来我们看看一个好的 Bug 报告该包含什么。 ## 哪里提交 Bug 报告 FreeBSD 项目建议用户通过多种渠道分享使用体验。按优先顺序，新 Bug 或有趣 Bug 的报告渠道如下： * 在 [reviews.freebsd.org](https://reviews.freebsd.org/) 上提交带有清晰测试的易于应用的变更 * 在 [reviews.freebsd.org](https://reviews.freebsd.org/) 上提交临时修补的解决方案 * 在 [bugs.freebsd.org](https://bugs.freebsd.org/) 上提交新的 Bug * 直接给开发者发邮件（或其他形式的沟通） * 在论坛上抱怨并推测原因 * 在 IRC、Matrix、Discord 或其他聊天渠道留言 * **在社交媒体上愤怒发帖，说 FreeBSD 是最差的** 前两种方式假定了较高的技术水平。如果这对你来说太难，也没关系，我们依然欢迎 Bug 报告。 我们不要求每个人都能做高级开发，只希望每位报告者在每一步尽可能提供相关细节。 ## 如何写好 Bug 报告 ### 应包含的信息 * 关于你环境的详细信息 * 你期望发生什么 * 实际发生了什么 * 期望与实际的差异 * 触发 Bug 的前因后果 * 时间因素（重启后立刻出现？还是运行 5 天后才出现？） ### 提供哪些资料 系统运行时会生成很多有助于调试的信息，你可能会被要求提供日志，例如： * `dmesg` 的输出 * panic 消息的完整文本和堆栈跟踪 * 硬件问题时 `pciconf -lv` 的输出 * syslog 输出 * 工具输出和错误信息 提供的资料宁多勿少；如果开发者不得不再来问你一次，可能会耽误至少一周。 ### 环境信息 报告时要清楚说明 FreeBSD 的版本，以及涉及多少主机。Bug 出现在 14 台和 15 台之间的差异，往往比只知道“14 台”更有意义。 说明是否有自定义，是否是自己编译的 FreeBSD，还是使用软件包。你是不是在用下游发行版，比如 pfSense 或 HardenedBSD？这不会让 FreeBSD 开发者拒绝帮助，但如果你隐瞒这一点，可能会惹恼他们。 ### 期望与实际 清晰地说明你期望发生什么，以及实际发生了什么。并明确指出差异。 ### 触发 Bug 的过程 描述清楚“做了 X 之后无法再做 Y”。这类报告对开发者尤其有价值。 ## 提供信息的方式 尽量以文本形式提供信息。错误消息要全部包含。如果系统 panic，实在没法复制，可以拍照，但最好同时抄录文字。Bug 跟踪系统里的文字记录可以保存几十年，图片链接往往会失效。 ## 优秀 Bug 报告的关键：复现步骤 一个好的 Bug 报告会包含复现步骤。简单问题可能只需要一个命令；复杂问题可能需要脚本配合。 复现的目标是尽量简化，缩减到最小必要条件。 ## 主动协助 提交 Bug 后，这可能已经足以让开发者感兴趣。如果你能在提交后的 20 分钟内指出一个回归或新 Bug，很可能立刻引起开发者关注。 Bug 被分配到团队需要时间，这是正常现象。你也可以主动联系相关领域的开发者，但要保持礼貌。 开发者接手 Bug 后，可能会问你问题；时间久了，可能会问：“在最新快照上还会出现吗？” 他们可能会请你提供更多信息或测试补丁。某些只出现在特定硬件上的 Bug，如果没人验证，补丁可能会长时间搁置。 ## 祝你好运！ 撰写并提交 Bug 报告是一件耗费精力的事，有时你会觉得自己的努力无人理睬。但 FreeBSD 是一项志愿者项目，开发者根据兴趣分配时间。我们拥有一群优秀的开发者，他们愿意追踪复杂而隐蔽的问题，但他们需要你的帮助与合作，收集足够的信息来复现和测试。 如果你遵循这里的建议，你会更顺利地让 Bug 获得关注，并推动它们被修复。 *** **Tom Jones**，FreeBSD 提交者，对保持网络栈高性能充满兴趣。 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://freebsd-journal-cn.bsdcn.org/2025789-qian-ru-shi/writing-effective-bug-reports.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.