问题报告处理指南

商标

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

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

1. 简介

Bugzilla 是 FreeBSD 项目使用的缺陷管理系统。由于准确跟踪未解决的软件缺陷对于 FreeBSD 的质量至关重要，因此正确使用该软件对于项目的向前发展至关重要。

整个 FreeBSD 社区都可以访问 Bugzilla。为了保持数据库的一致性并提供一致的用户体验，已经建立了涵盖缺陷管理常见方面的指南，例如提交后续操作、处理关闭请求等。

2. 问题报告生命周期

报告者在网站上提交错误报告。该错误处于 需要分类 状态。
Jane Random BugBuster 确认错误报告包含足够的信息以进行重现。如果不是，她会与报告者来回沟通以获取所需的信息。此时，错误被设置为 打开 状态。
Joe Random Committer 对 PR 感兴趣并将其分配给自己，或者 Jane Random BugBuster 认为 Joe 最适合处理它并将其分配给他。错误应设置为 讨论中 状态。
Joe 与发起者进行了简短的交流（确保所有内容都进入审计跟踪）并确定了问题的原因。
Joe 通宵加班编写了一个他认为可以解决问题的补丁，并在后续操作中提交了它，要求发起者对其进行测试。然后他将 PR 的状态设置为 补丁就绪。
经过几次迭代后，Joe 和发起者都对补丁感到满意，Joe 将其提交到 -CURRENT（如果问题不存在于 -CURRENT 中，则直接提交到 -STABLE），确保在提交日志中引用问题报告（并在他们提交了全部或部分补丁的情况下为发起者提供荣誉），并在适当情况下开始 MFC 倒计时。错误被设置为 需要 MFC 状态。
如果补丁不需要 MFC，则 Joe 将 PR 关闭为 问题已解决。

许多 PR 提交的信息很少，有些问题要么很难解决，要么只是触及了更大问题的一部分；在这些情况下，获取解决问题所需的所有必要信息非常重要。如果包含的问题无法解决或再次发生，则需要重新打开 PR。

3. 问题报告状态

在采取某些操作时更新 PR 的状态非常重要。状态应准确反映 PR 当前的工作状态。

示例 1. 关于何时更改 PR 状态的小示例

当 PR 已经过处理并且负责的开发人员对修复感到满意时，他们会向 PR 提交后续操作并将状态更改为“反馈”。此时，发起者应在他们的上下文中评估修复并回复，指示缺陷是否确实已解决。

问题报告可能处于以下状态之一

打开: 初始状态；问题已指出，需要审查。
已分析: 问题已审查，正在寻求解决方案。
反馈: 进一步的工作需要发起者或社区提供更多信息；可能是有关拟议解决方案的信息。
已修补: 补丁已提交，但某些事情（MFC 或发起者的确认）仍在等待。
已暂停: 由于缺乏信息或资源，问题没有得到处理。这是寻找项目的人的首选。如果问题根本无法解决，则会将其关闭，而不是暂停。文档项目将已暂停用于需要大量工作且目前没有人有时间完成的心愿清单项目。
已关闭: 当任何更改都已集成、记录和测试，或放弃修复问题时，问题报告将被关闭。

“已修补”状态与反馈直接相关，因此如果发起者无法测试补丁并且它在您自己的测试中有效，则您可以直接进入“已关闭”状态。

4. 问题报告类型

在处理问题报告时，无论是作为可以直接访问问题报告数据库的开发人员，还是作为浏览数据库并提交带有补丁、评论、建议或更改请求的后续操作的贡献者，您都会遇到几种不同类型的 PR。

以下部分描述了每种不同类型的 PR 的用途、PR 属于这些类型之一的时间以及每种不同类型接收的处理方式。

5. 未分配的 PR

当 PR 到达时，它们最初会被分配给一个通用的（占位符）分配者。这些始终以 freebsd- 开头。此默认值的精确值取决于类别；在大多数情况下，它对应于特定的 FreeBSD 邮件列表。以下是当前列表，最常见的列表首先列出

表 1. 默认分配者 - 最常见
类型	类别	默认分配者
基础系统	bin、conf、gnu、kern、misc	freebsd-bugs
特定于架构	alpha、amd64、arm、i386、ia64、powerpc、sparc64	freebsd-arch
端口集合	端口	freebsd-ports-bugs
随系统提供的文档	docs	freebsd-doc
FreeBSD 网页（不包括文档）	网站	freebsd-www

表 2. 默认分配者 - 其他
类型	类别	默认分配者
宣传工作	宣传	freebsd-advocacy
Java 虚拟机™ 问题	java	freebsd-java
标准合规性	标准	freebsd-standards
线程库	线程	freebsd-threads
usb(4) 子系统	usb	freebsd-usb

不要惊讶地发现 PR 的提交者将其分配给了错误的类别。如果您修复了类别，请不要忘记也修复分配。（特别是，我们的提交者似乎很难理解，仅仅因为他们的问题在 i386 系统上出现，并不意味着它可能是 FreeBSD 的通用问题，因此更适合 kern。当然，反之亦然。）

某些 PR 可以由任何人重新分配到这些通用分配者之外。有几种类型的分配者：专门的邮件列表；邮件别名（用于某些有限兴趣的项目）；和个人。

对于作为邮件列表的分配者，请在进行分配时使用长格式（例如，freebsd-foo 而不是 foo）；这将避免向邮件列表发送重复的电子邮件。

由于自愿担任某些类型 PR 的默认分配者的个人列表经常变化，因此更适合于 FreeBSD wiki。

这是一个此类实体的示例列表；它可能不完整。

表 3. 常用分配者 - 基础系统
类型	建议的类别	建议的分配者	分配者类型
特定于 ARM® 架构的问题	arm	freebsd-arm	邮件列表
特定于 MIPS® 架构的问题	kern	freebsd-mips	邮件列表
特定于 PowerPC® 架构的问题	kern	freebsd-ppc	邮件列表
高级配置和电源管理 (acpi(4)) 问题	kern	freebsd-acpi	邮件列表
异步传输模式 (ATM) 驱动程序问题	kern	freebsd-atm	邮件列表
嵌入式或小型 FreeBSD 系统（例如，NanoBSD/PicoBSD/FreeBSD-arm）问题	kern	freebsd-embedded	邮件列表
FireWire® 驱动程序问题	kern	freebsd-firewire	邮件列表
文件系统代码问题	kern	freebsd-fs	邮件列表
geom(4) 子系统问题	kern	freebsd-geom	邮件列表
与 ipfw(4) 子系统相关的问题	kern	freebsd-ipfw	邮件列表
与综合业务数字网络 (ISDN) 驱动程序相关的问题	kern	freebsd-isdn	邮件列表
jail(8) 子系统	kern	freebsd-jail	邮件列表
与 Linux® 或 SVR4 模拟相关的问题	kern	freebsd-emulation	邮件列表
与网络协议栈相关的问题	kern	freebsd-net	邮件列表
与 pf(4) 子系统相关的问题	kern	freebsd-pf	邮件列表
与 scsi(4) 子系统相关的问题	kern	freebsd-scsi	邮件列表
与 sound(4) 子系统相关的问题	kern	freebsd-multimedia	邮件列表
与 wlan(4) 子系统和无线驱动程序相关的问题	kern	freebsd-wireless	邮件列表
与 sysinstall(8) 或 bsdinstall(8) 相关的问题	bin	freebsd-sysinstall	邮件列表
与系统启动脚本 (rc(8)) 相关的问题	kern	freebsd-rc	邮件列表
与 VIMAGE 或 VNET 功能及相关代码相关的问题	kern	freebsd-virtualization	邮件列表
与 Xen 模拟相关的问题	kern	freebsd-xen	邮件列表

表 4. 常见指派人 - Ports 集合
类型	建议的类别	建议的分配者	分配者类型
与 ports 框架相关的问题（不包括单个端口！）	端口	portmgr	别名
由 apache@FreeBSD.org 维护的端口	端口	apache	邮件列表
由 autotools@FreeBSD.org 维护的端口	端口	autotools	别名
由 doceng@FreeBSD.org 维护的端口	端口	doceng	别名
由 eclipse@FreeBSD.org 维护的端口	端口	freebsd-eclipse	邮件列表
由 gecko@FreeBSD.org 维护的端口	端口	gecko	邮件列表
由 gnome@FreeBSD.org 维护的端口	端口	gnome	邮件列表
由 hamradio@FreeBSD.org 维护的端口	端口	hamradio	别名
由 haskell@FreeBSD.org 维护的端口	端口	haskell	别名
由 java@FreeBSD.org 维护的端口	端口	freebsd-java	邮件列表
由 kde@FreeBSD.org 维护的端口	端口	kde	邮件列表
由 mono@FreeBSD.org 维护的端口	端口	mono	邮件列表
由 office@FreeBSD.org 维护的端口	端口	freebsd-office	邮件列表
由 perl@FreeBSD.org 维护的端口	端口	perl	邮件列表
由 python@FreeBSD.org 维护的端口	端口	freebsd-python	邮件列表
由 ruby@FreeBSD.org 维护的端口	端口	freebsd-ruby	邮件列表
由 secteam@FreeBSD.org 维护的端口	端口	secteam	别名
由 vbox@FreeBSD.org 维护的端口	端口	vbox	别名
由 x11@FreeBSD.org 维护的端口	端口	freebsd-x11	邮件列表

具有端口提交者作为维护者的 Ports PR 可以由任何人重新分配（但请注意，并非每个 FreeBSD 提交者都是端口提交者，因此您不能仅根据电子邮件地址进行判断）。

对于其他 PR，请不要将其重新分配给个人（除您自己以外），除非您确定指派人确实希望跟踪该 PR。这将有助于避免没有人查看特定问题修复的情况，因为每个人都认为指派人已经在处理它。

表 5. 常见指派人 - 其他
类型	建议的类别	建议的分配者	分配者类型
与 PR 数据库相关的问题	bin	bugmeister	别名
与 Bugzilla 网页表单相关的问题。	doc	bugmeister	别名

6. 已指派的 PR

如果 PR 的 responsible 字段设置为 FreeBSD 开发人员的用户名，则表示该 PR 已移交给该特定人员进行进一步处理。

除指派人或 bugmeister 外，任何人都不应触碰已指派的 PR。如果您有评论，请提交后续回复。如果由于某种原因您认为 PR 应该更改状态或重新分配，请向指派人发送消息。如果指派人在两周内没有回复，请取消分配 PR 并按照您的意愿进行操作。

7. 重复的 PR

如果您发现多个描述相同问题的 PR，请选择包含最多有用信息的一个，并关闭其他 PR，并明确说明替代 PR 的编号。如果多个 PR 包含不重叠的有用信息，请在后续回复中将所有缺失的信息提交到一个 PR 中，包括对其他 PR 的引用；然后关闭其他 PR（现在已被完全取代）。

8. 过时的 PR

如果 PR 在六个月以上未被修改，则被认为是过时的。应用以下流程来处理过时的 PR

如果 PR 包含足够详细的信息，请尝试在 -CURRENT 和 -STABLE 中重现问题。如果成功，请提交详细说明您的发现的后续回复，并尝试找到可以指派给它的人。如果合适，将状态设置为“已分析”。
如果 PR 描述的问题您知道是由于使用错误（错误配置或其他）导致的，请提交后续回复说明发起者做错了什么，然后关闭 PR，理由为“用户错误”或“配置错误”。
如果 PR 描述的错误您知道已在 -CURRENT 和 -STABLE 中得到修复，请关闭它，并发送一条消息说明它是在每个分支中何时修复的。
如果 PR 描述的错误您知道已在 -CURRENT 中得到修复，但未在 -STABLE 中修复，请尝试找出修复它的人员何时计划将其 MFC，或尝试找到其他人（也许是您自己？）来执行此操作。将状态设置为“已修补”，并将其指派给将执行 MFC 的人。
在其他情况下，请要求发起者确认问题是否仍然存在于较新的版本中。如果发起者在一个月内没有回复，请关闭 PR，并附上“反馈超时”的注释。

9. 非错误 PR

遇到看起来应该发布到 FreeBSD 问题报告邮件列表或其他列表的开发人员应关闭 PR，并在评论中告知提交者为什么这不是真正的 PR 以及应将消息发布到哪里。

Bugzilla 监听传入 PR 的电子邮件地址已作为 FreeBSD 文档的一部分发布，并已在网站上发布和列出。这意味着垃圾邮件发送者发现了它们。

每当您关闭其中一个 PR 时，请执行以下操作

将组件设置为 junk（在 Supporting Services 下）。
将负责人设置为 nobody@FreeBSD.org。
将状态设置为 Issue Resolved。

将类别设置为 junk 使得很明显 PR 中没有有用的内容，并有助于减少主要类别中的混乱。

10. 进一步阅读

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

如何编写 FreeBSD 问题报告-针对 PR 发起者的指南。

最后修改时间：2024 年 9 月 20 日，作者：Fernando Apesteguía