编写 FreeBSD 问题报告

商标

FreeBSD 是 FreeBSD 基金会的注册商标。

IBM、AIX、OS/2、PowerPC、PS/2、S/390 和 ThinkPad 是国际商业机器公司在美国、其他国家/地区或两者的商标。

Intel、Celeron、Centrino、Core、EtherExpress、i386、i486、Itanium、Pentium 和 Xeon 是英特尔公司或其子公司在美国和其他国家/地区的商标或注册商标。

Sun、Sun Microsystems、Java、Java 虚拟机、JDK、JRE、JSP、JVM、Netra、OpenJDK、Solaris、StarOffice、SunOS 和 VirtualBox 是 Sun Microsystems, Inc.在美国和其他国家/地区的商标或注册商标。

制造商和销售商用来区分其产品的许多名称都被声明为商标。在本文档中出现这些名称的地方，并且 FreeBSD 项目知道商标声明，这些名称后面都已加上“™”或“®”符号。

目录

摘要

本文介绍如何最好地制定和提交问题报告给 FreeBSD 项目。

1. 简介

作为软件用户，最令人沮丧的经历之一就是提交问题报告，却得到简单粗暴的关闭，并附带一个简短且无帮助的解释，例如“不是 bug”或“虚假 PR”。类似地，作为软件开发人员，最令人沮丧的经历之一是被大量的问题报告所淹没，这些报告实际上并不是问题报告，而是支持请求，或者包含很少或根本没有关于问题是什么以及如何重现的信息。

本文档试图描述如何编写优质的问题报告。有人会问，什么是优质的问题报告？好吧，为了直截了当地说明，优质的问题报告是可以被迅速分析和处理的报告，从而让用户和开发者双方都满意。

虽然本文的主要重点是 FreeBSD 问题报告，但大部分内容应该也适用于其他软件项目。

请注意，本文的组织是以主题为基础的，而不是按时间顺序排列的。在提交问题报告之前，请通读整篇文档，而不是将其视为分步教程。

2. 何时提交问题报告

存在许多类型的问题，并非所有问题都应该产生问题报告。当然，没有人是完美的，有时看似程序中的 bug 实际上是对命令语法的误解或配置文件中的输入错误（尽管这本身有时可能表明应用程序的文档质量差或错误处理不佳）。仍然存在许多情况下，提交问题报告显然不是正确的做法，只会让提交者和开发人员都感到沮丧。相反，也有一些情况下，提交关于除 bug 之外其他事物的报告可能是合适的，例如增强功能或新功能。

那么如何确定什么是 bug，什么不是呢？作为一个简单的经验法则，如果问题可以用一个问题来表达（通常是“如何做 X？”或“在哪里可以找到 Y？”的形式），那么它不是 bug。情况并非总是如此黑白分明，但问题规则涵盖了绝大多数情况。在寻找答案时，可以考虑向FreeBSD 通用问题邮件列表提出问题。

在提交关于端口或其他非 FreeBSD 本身一部分的软件的 PR 时，请考虑以下因素

  • 请不要提交仅说明应用程序的新版本可用的问题报告。当应用程序的新版本可用时，端口维护者会自动通过 portscout 收到通知。更新端口到最新版本的实际补丁是受欢迎的。

  • 对于未维护的端口（MAINTAINER 为 ports@FreeBSD.org），没有包含补丁的 PR 不太可能被提交者采纳。要成为未维护端口的维护者，请提交包含请求的 PR（补丁优先，但不是必需的）。

  • 在这两种情况下，按照移植者手册中描述的过程将获得最佳结果。（您可能还想阅读为 FreeBSD 端口集合做出贡献。）

很少能修复无法重现的 bug。如果 bug 只出现过一次，您无法重现它，而且似乎没有其他人遇到过，那么开发人员很可能无法重现它或找出问题所在。这并不意味着它没有发生，但确实意味着您的问题报告导致 bug 修复的可能性非常小。更糟糕的是，通常此类 bug 实际上是由硬盘驱动器故障或处理器过热引起的——在提交 PR 之前，您应该始终尝试排除这些原因，并在可能的情况下。

接下来，要决定向谁提交问题报告，您需要了解构成 FreeBSD 的软件由几个不同的元素组成

  • 由 FreeBSD 贡献者编写和维护的基本系统中的代码，例如内核、C 库和设备驱动程序（分类为kern）；二进制实用程序（bin）；手册页和文档（docs）；以及网页（www）。这些区域的所有 bug 都应报告给 FreeBSD 开发人员。

  • 由其他人编写和维护的基本系统中的代码，并导入到 FreeBSD 中并进行调整。例如clang(1)和sendmail(8)。这些区域的大多数 bug 都应报告给 FreeBSD 开发人员；但在某些情况下，如果问题不是 FreeBSD 特定的，则可能需要将其报告给原始作者。

  • 不在基本系统中而是 FreeBSD 端口集合（类别ports）的一部分的单个应用程序。这些应用程序中的大多数不是由 FreeBSD 开发人员编写的；FreeBSD 提供的只是一个安装应用程序的框架。因此，仅当问题被认为是 FreeBSD 特定的时，才向 FreeBSD 开发人员报告问题；否则，请将其报告给软件的作者。

然后，确定问题是否及时。很少有事情会比收到关于她已经修复的 bug 的问题报告更让开发人员恼火。

如果问题出现在基本系统中，首先阅读FreeBSD 版本上的 FAQ 部分，如果您还不熟悉该主题。FreeBSD 不可能修复除基本系统某些最新分支之外的任何其他版本中的问题，因此提交关于旧版本 bug 报告可能只会导致开发人员建议您升级到受支持的版本以查看问题是否仍然存在。安全官员团队维护着受支持版本的列表。

如果问题出现在端口中，请考虑向上游提交 bug。FreeBSD 项目无法修复所有软件中的所有 bug。

3. 准备工作

一个好的规则是，在提交问题报告之前始终进行背景搜索。也许问题已经被报告过了；也许它正在邮件列表中讨论，或者最近讨论过；它甚至可能已经在比您正在运行的版本更新的版本中修复了。因此，在提交问题报告之前，您应该检查所有显而易见的地方。对于 FreeBSD，这意味着

  • FreeBSD常见问题解答（FAQ）列表。FAQ 试图为各种问题提供答案，例如关于硬件兼容性、用户应用程序和内核配置的问题。

  • 邮件列表。如果您没有订阅，请使用 FreeBSD 网站上的可搜索的存档。如果问题尚未在列表中讨论，您可以尝试发布一条关于它的消息，并等待几天看看是否有人可以发现一些被忽视的东西。

  • 可选地，整个网络——使用您喜欢的搜索引擎查找任何与问题相关的引用。您甚至可能会从您不知道或没有想过要搜索的已存档邮件列表或新闻组中获得点击量。

  • 接下来，可搜索的FreeBSD PR 数据库（Bugzilla）。除非问题是最近的或模糊的，否则它很可能已经被报告过了。

  • 最重要的是，尝试查看源代码库中现有的文档是否解决了您的问题。

    对于基础 FreeBSD 代码，您应该仔细研究系统上 /usr/src/UPDATING 的内容，或访问 https://cgit.freebsd.org/src/tree/UPDATING 查看最新版本。（如果您要从一个版本升级到另一个版本，尤其是在升级到 FreeBSD-CURRENT 分支时，此信息至关重要）。

    但是，如果问题出现在作为 FreeBSD Ports Collection 的一部分安装的内容中，则应参考 /usr/ports/UPDATING（针对单个端口）或 /usr/ports/CHANGES（针对影响整个 Ports Collection 的更改）。https://cgit.freebsd.org/ports/tree/UPDATING 和 https://cgit.freebsd.org/ports/tree/CHANGES 也可通过 cgit 访问。

4. 编写问题报告

既然您已经确定您的问题值得提交问题报告，并且它是一个 FreeBSD 问题，那么现在是时候编写实际的问题报告了。在我们深入了解用于生成和提交 PR 的程序的机制之前，这里有一些提示和技巧，可以帮助确保您的 PR 能够达到最佳效果。

5. 编写高质量问题报告的提示和技巧

  • 不要留空“摘要”行。 PR 既会发送到全球范围内的邮件列表（其中“摘要”用于 Subject: 行），也会进入数据库。任何后来浏览数据库并按概要查找 PR 的人，如果发现 PR 的主题行为空，往往会直接跳过它。请记住，PR 会保留在这个数据库中，直到有人关闭它；匿名 PR 通常会淹没在噪音中而消失。

  • 避免使用弱化的“摘要”行。 您不应该假设任何阅读您 PR 的人都了解您提交的背景，因此，您提供的信息越多越好。例如，问题适用于系统的哪个部分？您是否仅在安装期间或运行期间遇到问题？举例来说，与 Summary: portupgrade is broken 相比，Summary: port ports-mgmt/portupgrade coredumps on -current 则提供了更多信息。（在端口的情况下，在“摘要”行中包含类别和端口名称尤其有用。）

  • 如果您有补丁，请说明。 补丁的存在使报告更容易处理。

    • 不要使用 patch 或 patch-ready 关键字 - 它们已弃用。

  • 如果您是维护者，请说明。 如果您正在维护一部分源代码（例如，现有端口），则绝对应该将 PR 的“类别”设置为 maintainer-update。这样，任何处理您的 PR 的提交者都不必进行检查。

  • 请具体说明。 您提供有关所遇到问题的详细信息越多，获得回复的可能性就越大。

    • 包含您正在运行的 FreeBSD 版本（下面有一个位置可以填写）以及架构。您应该说明是从发行版（例如，从 CD-ROM 或下载）运行，还是从 Git 维护的系统运行（如果是，则说明您所在的哈希值和分支）。如果您正在跟踪 FreeBSD-CURRENT 分支，那么这将是其他人首先询问的内容，因为修复程序（特别是针对高知名度问题的修复程序）往往会非常快地提交，并且预计 FreeBSD-CURRENT 用户会跟上进度。

    • 包含您在 make.conf、src.conf 和 src-env.conf 中指定的全局选项。由于选项数量无限，因此并非每种组合都得到完全支持。

    • 如果问题可以轻松重现，请包含有助于开发人员自己重现问题的信息。如果可以通过特定输入来演示问题，则尽可能包含该输入的示例，并包含实际输出和预期输出。如果此数据量很大或无法公开，则尝试创建一个展示相同问题的最小文件，并将其包含在 PR 中。

    • 如果这是一个内核问题，那么请准备好提供以下信息。（您不必默认包含这些信息，因为这只会导致数据库膨胀，但您应该包含您认为可能相关的摘录）

      • 您的内核配置（包括已安装的硬件设备）

      • 是否启用了调试选项（例如 WITNESS），如果启用了，则说明在更改该选项的含义时问题是否仍然存在

      • 任何回溯、恐慌或其他控制台输出的完整文本，或 /var/log/messages 中的任何条目，如果已生成

      • 如果您的问题与特定硬件相关，则输出 pciconf -l 和 dmesg 输出的相关部分

      • 您已阅读 src/UPDATING 并且您的问题未在其中列出这一事实（肯定有人会问）

      • 您是否可以运行任何其他内核作为备用（这是为了排除与硬件相关的故障，例如磁盘故障和 CPU 过热，这些故障可能伪装成内核问题）

    • 如果这是一个端口问题，那么请准备好提供以下信息。（您不必默认包含这些信息，因为这只会导致数据库膨胀，但您应该包含您认为可能相关的摘录）

      • 您已安装的端口

      • 任何覆盖 bsd.port.mk 中默认值的的环境变量，例如 PORTSDIR

      • 您已阅读 ports/UPDATING 并且您的问题未在其中列出这一事实（肯定有人会问）

  • 避免模糊的功能请求。 形式为“有人应该真正实现一个能够做某事的东西”的 PR 比非常具体的请求获得结果的可能性更小。请记住，源代码对所有人开放，因此，如果您想要一个功能，确保其被包含的最佳方法是开始着手！此外，请考虑诸如此类的事情更适合在 freebsd-questions 上讨论，而不是在 PR 数据库中作为条目，如上所述。

  • 确保没有人提交过类似的 PR。 虽然这已在上面提到过，但在这里重复一遍。使用位于 https://bugs.freebsd.org/bugzilla/query.cgi 的基于 Web 的搜索引擎只需一两分钟。（当然，每个人都难免会忘记这样做。）

  • 每个问题报告只报告一个问题。 除非问题相关，否则避免在一个报告中包含两个或多个问题。提交补丁时，除非补丁密切相关，否则避免在同一个 PR 中添加多个功能或修复多个错误——此类 PR 通常需要更长的时间才能解决。

  • 避免有争议的请求。 如果您的 PR 涉及过去存在争议的领域，您可能需要做好不仅提供补丁，还提供理由说明补丁为何是“正确的事情”的准备。如上所述，使用位于 https://freebsd.ac.cn/search/#mailinglists 的档案仔细搜索邮件列表始终是一个良好的准备工作。

  • 请礼貌。 几乎任何可能处理您的 PR 的人都志愿者。没有人喜欢被告知他们必须做某事，而他们已经出于某些非金钱动机的驱使在做了。在开源项目中，始终牢记这一点。

6. 在开始之前

类似的考虑也适用于使用 基于 Web 的 PR 提交表单。请注意剪切粘贴操作可能会更改空格或其他文本格式。

最后，如果提交内容很长，请脱机准备工作，以便在提交过程中出现问题时不会丢失任何内容。

7. 附加补丁或文件

通常，我们建议使用 git format-patch 生成一个或一系列针对基础分支（例如 origin/main）的统一 diff。以这种方式生成的补丁将包含 Git 哈希值，并将包含您的姓名和电子邮件地址，使提交者更容易应用您的补丁并正确地将您记为作者（使用 git am）。对于您更倾向于不使用 git 的次要更改，请务必使用 diff(1) 并使用 -u 选项创建统一 diff，因为这会为开发人员提供更多上下文，并且比其他 diff 格式更易读。

对于内核或基本实用程序的问题，建议使用针对 FreeBSD-CURRENT（主 Git 分支）的补丁，因为所有新代码都应该首先在该分支上应用和测试。在完成适当或大量的测试后，代码将被合并/迁移到 FreeBSD-STABLE 分支。

如果您将补丁内联附加，而不是作为附件，请注意，最常见的问题是某些电子邮件程序倾向于将制表符渲染为空格，这将完全破坏旨在作为 Makefile 一部分的任何内容。

不要使用 Content-Transfer-Encoding: quoted-printable 将补丁作为附件发送。这些将执行字符转义，并且整个补丁将毫无用处。

另请注意，虽然在 PR 中包含小补丁通常是可以的——尤其是在它们修复了 PR 中描述的问题时——但大型补丁，尤其是可能需要大量审查才能提交的新代码，应该放置在 Web 或 ftp 服务器上，并且 URL 应包含在 PR 中，而不是补丁中。电子邮件中的补丁往往会被损坏，补丁越大，相关方解开它的难度就越大。此外，在 Web 上发布补丁允许您修改它，而无需在原始 PR 的后续操作中重新提交整个补丁。最后，大型补丁只会增加数据库的大小，因为已关闭的 PR 实际上不会被删除，而是被保留并简单地标记为已完成。

您还应该注意，除非您在您的 PR 或补丁本身中明确说明，否则您提交的任何补丁都将被假定为根据与您修改的原始文件相同的条款获得许可。

8. 填写表单

您使用的电子邮件地址将成为公开信息，并可能提供给垃圾邮件发送者。您应该已经制定了垃圾邮件处理程序，或使用临时电子邮件帐户。但是，请注意，如果您根本不使用有效的电子邮件帐户，我们将无法向您询问有关您的 PR 的问题。

当您提交错误时，您会发现以下字段

  • 摘要：请用简短且准确的描述填写此字段，以描述问题。摘要用作问题报告电子邮件的主题，并用于问题报告列表和摘要中；摘要模糊的问题报告往往会被忽略。

  • 严重程度：仅影响我、影响某些人或影响很多人之一。不要过度反应；除非问题确实如此，否则不要将您的问题标记为影响很多人。由于有太多其他人也这样做过，因此 FreeBSD 开发人员不一定会因为您夸大了问题的重要性而更快地处理您的问题。

  • 类别：选择合适的类别。

    首先，您需要确定问题出在系统的哪个部分。请记住，FreeBSD 是一个完整的操作系统，它安装了内核、标准库、许多外围设备驱动程序以及大量实用程序（“基础系统”）。但是，Ports Collection 中还有数千个其他应用程序。您首先需要确定问题是出在基础系统中，还是通过 Ports Collection 安装的某个东西。

    以下是主要类别的描述

    • 如果问题与内核、库（例如标准 C 库libc）或基础系统中的外围设备驱动程序有关，一般情况下您将使用kern类别。（有一些例外情况；请参见下文）。通常，这些是在手册页的第 2、3 或 4 节中描述的内容。

    • 如果问题与二进制程序（例如sh(1)或mount(8)）有关，您首先需要确定这些程序是位于基础系统中还是通过 Ports Collection 添加的。如果您不确定，可以使用whereis programname。FreeBSD 的 Ports Collection 约定是将所有内容安装在/usr/local下，尽管系统管理员可以覆盖此约定。对于这些，您将使用ports类别（是的，即使端口的类别是www；请参见下文）。如果位置是/bin、/usr/bin、/sbin或/usr/sbin，则它是基础系统的一部分，您应该使用bin类别。这些都是在手册页的第 1 节或第 8 节中描述的内容。

    • 如果您认为错误存在于启动(rc)脚本中，或某种其他不可执行的配置文件中，则正确的类别是conf（配置）。这些是在手册页的第 5 节中描述的内容。

    • 如果您在文档集中（文章、书籍、手册页）或网站中发现了问题，正确的选择是docs。

      如果您遇到来自名为www/someportname的端口的问题，这仍然属于ports类别。

      还有一些更专业的类别。

    • 如果问题原本应归类于kern，但与 USB 子系统有关，则正确的选择是usb。

    • 如果问题原本应归类于kern，但与线程库有关，则正确的选择是threads。

    • 如果问题原本在基础系统中，但与我们对 POSIX® 等标准的遵守有关，则正确的选择是standards。

    • 如果您确信问题只会出现在您正在使用的处理器架构下，请选择其中一个特定于架构的类别：通常对于 32 位模式下的 Intel 兼容机器，选择i386；对于以 64 位模式运行的 AMD 机器，选择amd64（这也包括以 EMT64 模式运行的 Intel 兼容机器）；不太常见的是arm或powerpc。

      这些类别经常被错误地用于“我不知道”的问题。与其猜测，不如直接使用misc。

      示例 1. 架构特定类别的正确用法

      您有一台普通的基于 PC 的机器，并且认为遇到了特定于某个芯片组或某个主板的问题：i386是正确的类别。

      示例 2. 架构特定类别的错误用法

      您在常见的总线上遇到外置外设卡的问题，或者遇到特定类型硬盘驱动器的问题：在这种情况下，它可能适用于多个架构，而kern是正确的类别。

    • 如果您真的不知道问题出在哪里（或者解释似乎不适合上述内容），请使用misc类别。在这样做之前，您可能希望先在FreeBSD 通用问题邮件列表上寻求帮助。您可能会被告知现有类别中的一个实际上是更好的选择。

  • 环境：这应该尽可能准确地描述观察到问题所在的环境。这包括操作系统版本、包含问题的特定程序或文件的版本，以及任何其他相关项目，例如系统配置、影响问题安装的其他软件等——简单来说，开发人员需要知道的一切，以便重建发生问题的环境。

  • 描述：您遇到的问题的完整而准确的描述。除非您确定自己走在了正确的道路上，否则请避免推测问题的原因，因为它可能会误导开发人员对问题做出错误的假设。它应该包括您需要采取的重现问题的操作。如果您知道任何解决方法，请包含在内。它不仅可以帮助遇到相同问题的其他人解决问题，还可以帮助开发人员了解问题的原因。

9. 后续

问题报告提交后，您将收到一封确认电子邮件，其中包含分配给您的问题报告的跟踪编号以及用于检查其状态的 URL。如果幸运的话，有人会对您的问题感兴趣并尝试解决它，或者，在适当的情况下，解释为什么它不是问题。您将自动收到任何状态更改的通知，并且您将收到任何评论或补丁的副本，这些评论或补丁有人可能附加到您的问题报告的审计跟踪中。

如果有人向您索取其他信息，或者您记起了或发现了在初始报告中未提及的内容，请提交后续报告。错误无法修复的首要原因是与发起者缺乏沟通。最简单的方法是在单个 PR 的网页上使用评论选项，您可以从PR 搜索页面访问该网页。

如果问题在消失后问题报告仍然处于打开状态，只需添加一条评论说问题报告可以关闭，如果可能，解释问题是如何或何时解决的。

有时会有一到两周的延迟，问题报告在此期间保持未触碰状态，没有任何人分配或评论。当问题报告积压增加或在节假日期间，这种情况可能会发生。当问题报告在几周后仍未得到关注时，值得找到对解决问题特别感兴趣的提交者。

有几种方法可以做到这一点，理想情况下按照以下顺序，并在尝试每个通信渠道之间间隔几天

  • 向相关列表发送电子邮件，寻求对报告的评论。

  • 加入相关的 IRC 频道。部分列表如下：https://wiki.freebsd.org/IRC/Channels。告知该频道中的人员有关问题报告并寻求帮助。请耐心等待并在发布后留在频道中，以便来自世界各地不同时区的人员有机会赶上进度。

  • 找到对报告的问题感兴趣的提交者。如果问题出在某个特定工具、二进制文件、端口、文档或源文件中，请检查Git 存储库。找到最近几个对该文件进行实质性更改的提交者，并尝试通过 IRC 或电子邮件联系他们。提交者及其电子邮件列表可以在FreeBSD 贡献者文章中找到。

请记住，这些人是志愿者，就像维护人员和用户一样，因此他们可能无法立即提供帮助来处理问题报告。建议并感谢您在后续工作中保持耐心和一致性。只要对后续流程投入足够的关注和努力，找到提交者来处理问题报告只是时间问题。

10. 如果存在问题

如果您发现错误系统存在问题，请提交错误！有一个类别专门用于此目的。如果您无法这样做，请联系 bug 管理员，地址为bugmeister@FreeBSD.org。

11. 进一步阅读

这是一个与问题报告的正确编写和处理相关的资源列表。它绝不完整。

上次修改时间：2023 年 7 月 22 日，作者 Minsoo Choo