# 22.1 Bug 报告流程

规范的缺陷（Bug）报告流程是保障软件质量与维护者及用户协作的关键环节，不仅能提高问题解决效率，还能促进社区的知识共享与技术进步。

> **技巧**
>
> 在提交 Bug 报告前，建议先发送到邮件列表咨询，以确认问题性质并避免重复报告浪费社区人力资源。

FreeBSD 缺陷（Bug）报告系统位于 <https://bugs.freebsd.org/bugzilla>，提供标准化的缺陷跟踪与管理流程，是 FreeBSD 项目质量保障的核心基础设施。

遇到问题时，应按以下流程处理：

首先，确认问题不是由用户自身的操作或配置引起的。可采取以下排查步骤：

* 查阅常见问题列表、文档或手册等资料；
* 使用搜索引擎搜索相关信息；
* 搜索以往邮件列表，查看是否有人报告过类似问题；
* 在邮件列表中提问。

如果在刚升级的系统中遇到问题，请查看 **/usr/src/UPDATING** 文件的说明；如果是刚升级的第三方软件，请查看 **/usr/ports/UPDATING** 和 **/usr/ports/CHANGES** 文件。

相关文件结构：

```sh
/usr/
├── src/
│   └── UPDATING # 系统升级说明文件
├── ports/
│   ├── UPDATING # Ports 升级说明文件
│   └── CHANGES # Ports 变更记录文件
└── var/
    └── log/
        └── messages # 系统日志文件
```

然后，判断这是否是 **bug**。如果这个问题可以用问句来表示（例如“我怎么做……，哪里有……”），那么请先去 FreeBSD 邮件列表询问。

如果确认这是缺陷（bug），请核实系统版本是否仍受支持，否则可能无人处理。

需要确认该缺陷（bug）是否已被修复：

* 检查系统版本，确认是否有更新和补丁；
* 搜索 FreeBSD bug 管理系统，确认是否有人报告过类似的问题。

如果没有人报告过类似问题，那么就可以提交报告。

以下类型的问题不应提交：

* 某个应用已有新版本（通常会有自动通知告知维护者）；
* 对于无人维护的软件，如果没有补丁，仅报告缺陷（bug）可能不会得到处理；若想维护该软件，请提交相关请求；
* 如果不能使问题复现，那么别人也很难解决；
* 提出增加新功能的请求（可以在 FreeBSD 邮件列表中讨论，但建议先自行实现后再提交）。

决定问题应报告给谁：

* 对于基本系统组件、文档或网站问题，请直接向 FreeBSD 开发者提交报告；
* 对于那些随系统发行但由他人维护的软件，除非能确定问题与系统无关，否则也请提交给 FreeBSD 开发者；
* 对于那些第三方软件，除非能确定问题与系统有关，否则请提交给软件开发者。

报告的书写提示：

* 不要将“Summary”栏留空，因为它将作为邮件的标题；；
* “Summary”要有代表性，简明扼要；
* 如果有补丁，一定要上传；
* 注明系统版本和计算机架构，如果是自行编译的软件，还需说明编译设置；
* 如果问题可以复现，注明问题产生的条件；
* 如果是内核问题，请准备以下信息：硬件配置、内核配置、是否开启调试选项、错误信息或 /var/log/messages，并声明已查看 **/usr/src/UPDATING** 但问题未解决（因为有人会问），以及是否可以运行其他内核；
* 如果是第三方软件问题，请准备好：安装的软件，覆盖了 bsd.port.mk 的默认设置的所有环境变量，声明已经看过了 /usr/ports/UPDATING 并没有解决问题（因为总有人会问）；
* 每份报告应只包含一个问题，除非多个问题之间有紧密关联；
* 对有争议的问题要慎重，最好先讨论一下；
* 注意排版格式，尤其是在复制粘贴内容时；
* 记得备份报告，以防网络状况不佳导致提交失败；
* 保持礼貌，报告的接收者大多是无偿志愿者，请给予理解。

下面介绍 Bug 报告的填写：

注意，邮件是公开的，可能会收到骚扰，请采取防护措施或使用公共邮箱。

* Summary：梗概，简明扼要；
* Severity：严重程度，只影响我/影响某些人/影响许多人，不要过高评价；
* Category：类别；
  * kern 内核、库、内置驱动（手册 2-4），除了 USB 子系统、多线程库之外；
  * bin 内置程序；
  * ports 第三方程序；
  * conf 配置文件或者启动脚本（man 5）；
  * docs 文档或网站；
  * usb USB 子系统；
  * threads 多线程库；
  * standards 标准遵循；
  * （架构名称）与架构有关；
  * misc 其他，或者真的找不出来问题（最好先问问邮件列表）；
* Environment 环境，包括系统版本、程序版本、系统配置等；
* Description（问题描述）：内容应完整、详细，不要加入个人猜测。

FreeBSD 开发人员有限，因此缺陷（bug）报告可能长时间无人处理，也不一定会被解决。报告接收者大多是志愿者，因此不应过于苛求。如果可能，请先自行解决问题，再提交到上游。

> **技巧**
>
> [FreeBSD 的 GrimoireLab 监控面板](https://grimoire.freebsd.org/) 提供了 FreeBSD 项目目前的缺陷（bug）报告状态概览，展示项目开发活动与社区贡献的数据分析，可以帮助我们直观地了解情况。

## 课后习题

1. 查找一个已提交的 FreeBSD 内核 Bug 报告，分析其包含的信息完整性，并复现其报告的过程尝试解决。
2. 选择 GrimoireLab 监控面板的某类指标，分析其数据变化趋势，并讨论该趋势如何反映 FreeBSD 社区的协作模式。
3. 设计一个简单的测试场景，模拟发现一个 ports 软件缺陷，准备完整报告材料并在本地测试提交流程。