缺陷报告指南

在 Gitlab 中的 Arch Linux 缺陷跟踪器上打开（和关闭）缺陷报告是帮助社区的众多可能方式之一。然而，格式不佳的缺陷报告可能会适得其反。当缺陷报告不正确时，开发人员会浪费时间调查和关闭无效报告。本文档将指导任何希望通过有效报告和查找缺陷来帮助社区的人。

另请参阅：Simon Tatham 的如何有效地报告缺陷

报告前

准备一份详细且格式良好的缺陷报告并不困难，但需要报告者付出努力。在报告缺陷之前完成的工作可以说是这项工作中最有用的部分。不幸的是，很少有人花时间正确地完成这项工作。

以下步骤将指导您准备缺陷报告或功能请求。

搜索重复项

如果您遇到问题或想要新功能，很可能其他人已经遇到过这个问题或有过这个想法。如果是这样，则可能已存在合适的缺陷报告。在这种情况下，请不要创建重复报告；请参阅#跟进缺陷。

彻底搜索现有信息，包括

Arch Linux 论坛：论坛通常是用户寻求帮助或分享想法的第一站。虽然解决方案可能尚未存在，但额外的背景信息和讨论可以引导您朝着正确的方向前进。
Arch Linux 缺陷跟踪器：您的问题可能已报告给 Arch Linux 开发人员。重复的缺陷报告毫无帮助，并且会被迅速关闭。通过在“高级”下选择“所有状态”来搜索已关闭的缺陷以及未解决的报告。请记住标记“搜索详细信息”和/或“搜索评论”在“高级”下，缺陷标题可能不包含您正在搜索的文本。
Google 或您喜欢的搜索引擎：使用程序名称、版本以及相关的错误消息部分（如果有）进行搜索。
上游论坛、邮件列表和缺陷跟踪器：如果 Arch Linux 不对缺陷负责，则应将其报告给上游，而不是 Arch Linux 缺陷跟踪器。搜索最近关闭的缺陷以及未解决的报告。缺陷可能已在程序的开发版本中修复。
其他发行版论坛：自由软件社区非常庞大；Arch 用户不是唯一有想法的用户！例如，考虑搜索Gentoo 论坛、FedoraForum.org 和 Ubuntu 论坛。

上游还是 Arch？

Arch Linux 是一个 GNU/Linux发行版。Arch 开发人员和信任用户负责从各种来源编译、打包和分发软件。上游指的是这些来源——在 Arch Linux 中分发的软件的原始作者或维护者。例如，流行的 Firefox 网页浏览器由 Mozilla 项目开发。

如果 Arch 不对缺陷负责，则通过向 Arch 开发人员报告缺陷将无法解决问题。当缺陷不是通过发行版的移植和集成工作引起的时，则认为缺陷的责任在于上游。

通过向上游报告缺陷，您不仅可以帮助 Arch 用户和 Arch 开发人员，还可以帮助自由软件社区中的其他人，因为解决方案将向下传播到所有发行版。

一旦您向上游报告了缺陷或从上游找到了其他相关信息，则可能有助于将其发布在 Arch 缺陷跟踪器中，以便 Arch 开发人员和用户都知道它。

那么 Arch Linux 负责什么呢？

Arch Linux 项目：pacman、AUR、mkinitcpio、Arch 网站。如果您不确定项目是否属于 Arch，请显示软件包信息（pacman -Qi 软件包名称或使用网站）并查看上游 URL。
注意： 在 gitlab.archlinux.org 或 GitHub 上的项目上游问题跟踪器中报告 Arch Linux 软件项目的问题，而不是各自的软件包问题。
打包：打包基本上包括从上游获取源代码，使用相关选项编译它，确保它将被正确安装在 Arch 系统上，并检查主要功能是否正常工作。Arch 的打包不包括添加新功能或现有缺陷的补丁；这是上游开发人员的工作。

如果缺陷/功能不属于 Arch 的责任范围，请将其报告给上游。另请参阅#不属于缺陷的原因。

缺陷还是特性？

缺陷: 应该工作但无法工作的东西，与开发人员的意图相反。
特性: 软件现在或将来可以实现的功能，如果有人对其进行编码。

不属于缺陷的原因

您希望某件软件执行的功能，但上游开发人员未实现。简而言之：新功能。
已向上游报告的缺陷。
已在上游修复但不在 Arch 中的缺陷，因为软件包不是最新的。
软件包不是最新的。在 Arch 软件包网站上使用标记软件包过期功能。
软件包未使用 Fedora、Ubuntu 或其他社区补丁。补丁应提交给上游。
软件包中非必要功能 X 或功能 Y 未激活。这是一个功能请求。
软件包不包含 .desktop 文件或图标或其他 freedesktop 内容。如果源 tarball 中未包含此类文件，则这不是缺陷，必须将其作为功能请求上游请求。如果上游提供了此类文件，但在软件包中未使用，则这是一个缺陷。

不属于特性的原因

当它是缺陷时...
当实现该特性不属于 Arch 的责任范围时，即上游特性。
软件包不是最新的。在 Arch 软件包网站上使用标记软件包过期功能。
软件包未使用 Fedora、Ubuntu 或其他社区补丁。补丁应提交给上游。

收集有用的信息

以下是缺陷报告中应提及的有用信息列表

正在使用的软件包版本。始终指定软件包版本。说“最新的”、“今天的”或“extra 中的软件包”没有任何意义。特别是如果缺陷不会立即得到修复。
软件包使用的主要库的版本（在 PKGBUILD 中的 depends 变量中可用），当它们与问题相关时。如果您不确切知道要提供哪些信息，请等待缺陷查找者向您询问...
如果您遇到硬件相关问题，则使用的内核版本。
指示该功能是否曾经工作过。如果是，请指出何时停止工作。
当您遇到硬件相关问题时，请指出您的硬件品牌
添加相关的日志信息（如果有）。这可以从以下位置获得，具体取决于问题
- systemd 日志。如果使用 syslog-ng，则 /var/log/messages 包含与内核和硬件相关问题的日志。
- ~/.local/share/xorg/Xorg.0.log 或 /var/log/Xorg.0.log 或 /var/log/Xorg.2.log 或任何类似 Xorg 的日志文件，如果与视频相关的问题（nvidia、ati、xorg...）
- 在控制台中运行您的程序，并使用verbose和/或debug模式（如果可用）（请参阅您的程序文档），并将输出复制到文件中。在终端中运行应用程序时，请确保相关信息以英语显示，以便更多人可以理解它。这可以通过使用 export LC_ALL=C.UTF-8 来完成。以下示例使用名为 foobar 的软件，您希望从中获得运行时相关信息，并假设 foobar 具有 --verbose 选项
```
$ export LC_ALL=C.UTF-8
$ foobar --verbose
```
  这只会影响当前终端，并在终端关闭时停止生效。

如果您必须粘贴大量文本，例如 dmesg 的输出或 Xorg 日志，则最好将其保存为计算机上的文件并将其附加到缺陷报告中。通常，附加文件而不是使用 pastebin 来呈现相关信息是更可取的，因为 pastebin 内容可能会因链接过期或任何其他潜在问题而受到影响。附加文件保证所提供的信息始终可用。

指示如何重现缺陷。这非常重要，它将帮助人们在自己的计算机上测试缺陷和潜在补丁。
堆栈追踪。它是程序在其执行期间进行的调用的列表，有助于找到程序中缺陷所在的部分，尤其是在缺陷涉及程序崩溃的情况下。您可以使用 gdb（GNU 调试器）获取堆栈追踪，如调试/获取追踪#获取追踪中所述。

打开缺陷报告

当您确定它是缺陷或功能并且您收集了所有有用的信息时，就可以打开缺陷报告或功能请求了。

创建账户

您必须在 Arch GitLab 上创建一个帐户，它通过 Arch Linux SSO 管理其登录。

注意： 由于垃圾邮件的涌入，我们不得不暂时禁用帐户注册。如果您想获得访问权限，请发送电子邮件至 accountsupport@archlinux.org，并提供您想要的用户名。

在哪里打开缺陷报告

一旦您确定您的功能或缺陷与 Arch 相关而不是上游问题，您将需要在正确的项目中提交您的问题。这最容易通过 archlinux.org 上各个软件包页面上的添加新缺陷来完成。

您也可以选择使用 devtools 中的 pkgctl 来访问正确的页面

$ pkgctl repo web pkgname

AUR 中软件包的问题不会在缺陷跟踪器中报告。AUR 允许您向软件包添加评论，您应该使用这些评论向软件包维护者报告缺陷。

标题

请为您的缺陷/功能请求编写简洁明了的标题。

以下是一些建议

不要将您的报告命名为“软件包名称在上次更新后损坏” - 这是非描述性的，“上次更新后”在 Arch 中没有任何意义。
不要在标题中写太多文字。过多的文字在报告列表中将不可见。

严重性

本文或章节已过时。

原因： 用户自己无法为 GitLab 问题分配标签。（在Talk:Bug reporting guidelines中讨论）

选择严重性不会帮助更快地解决缺陷。它只会使真正严重的问题变得不那么明显，并可能使分配给您的缺陷的开发人员不太愿意修复它。

以下是严重性的一般用法

严重 - 系统崩溃、可能影响到您自己以外的严重启动失败，或核心或面向外部的服务软件包中的可利用安全问题。
高 - 应用程序的主要功能无法工作、不太严重的安全问题等。
中 - 非必要功能无法工作、不符合 UNIX 标准等。
低 - 可选功能（插件或编译激活）无法工作。
非常低 - 翻译或文档错误。一些实际上并不重要，但应该在未来版本中注意到的事情。

包含相关信息

这可能是缺陷报告中最困难的部分之一。您必须从#收集有用的信息部分中选择您将添加到缺陷报告中的信息。这将取决于您的问题是什么。如果您不知道相关的信息是什么，请不要害羞：提供的信息越多越好，而不是不够。

有关报告缺陷的良好教程可以在https://www.chiark.greenend.org.uk/~sgtatham/bugs.html找到。

但是，如果需要，开发人员或缺陷查找者会要求您提供更多信息。幸运的是，在提交一些缺陷报告后，您将知道应该提供哪些信息。

简短的信息可以内联在您的缺陷报告中，而长信息（日志、屏幕截图...）应附加。

跟进缺陷

不要认为一旦您报告了缺陷，工作就完成了!

开发人员或其他用户可能会要求您提供更多详细信息，并为您提供一些潜在的修复程序以供尝试。如果没有持续的反馈，缺陷将无法关闭，最终结果是用户和开发人员都很生气。

投票和关注

您可以通过问题上的表情为自己喜欢的缺陷投票。表情的数量向开发人员表明有多少人受到缺陷的影响，而不会产生太多噪音。但是，这不是解决缺陷的非常有效的方法。更重要的是发布您知道的关于缺陷的任何额外信息，如果您不是原始报告者。

关注缺陷非常重要：当添加新评论或缺陷状态发生更改时，您将收到电子邮件。这可以通过右上角“...”菜单中的切换通知开关来完成。如果您打开了一个问题或对其进行了评论，您将自动订阅更改。

回复额外信息请求

人们会花时间查看您的缺陷报告，并尝试帮助您。您需要继续帮助他们解决您的缺陷。不回答他们的问题将使您的缺陷无法解决，并可能阻碍修复缺陷的热情。

如果被要求，请花时间向人们提供更多信息，并尝试提出的解决方案.

如果您在几周或一个月后不回答问题，开发人员或缺陷查找者将关闭您的缺陷。

当新软件包版本发布时更新缺陷报告

有时，缺陷仅存在于给定软件包的某些版本中，并且缺陷已在新版本的软件包中修复。如果是这种情况，请在缺陷报告评论中说明，并请求关闭缺陷。

解决后关闭

有时人们报告了一个缺陷，但没有在自己解决后通知，导致人们搜索已经找到的解决方案。如果您找到了解决方案，请关闭缺陷，并在缺陷报告评论中给出解决方案。

缺陷状态

在其生命周期中，缺陷可能会经历几种状态

未确认 - 这是默认状态。您刚刚报告了它，但没有人设法重现问题或确认它实际上是一个缺陷。
新建 - 缺陷已确认，但尚未分配给负责相关软件的开发人员。通常情况下，需要更多调查来确定哪个软件负责该缺陷。
已分配 - 缺陷已分配给负责缺陷中涉及的软件的开发人员。这并不意味着开发人员将是修复缺陷的人。这甚至不意味着开发人员将致力于解决方案。这仅意味着开发人员将负责缺陷的生命周期，包括审查补丁（如果有）、发布修复程序以及在需要时关闭缺陷。直接联系开发人员并要求他们更快地修复它是不明智的；他们肯定不喜欢这样。
研究中 - 有人正在寻找解决方案。这种状态在 Arch 中很少使用，这是有充分理由的。研究中状态可能会使人们认为他们不需要对缺陷报告感兴趣。但通常我们需要不止一个人来修复缺陷：有几位经验丰富的人员处理缺陷会很有帮助。
等待回复和需要测试 - 报告缺陷的人已被要求提供更多信息或尝试提出的解决方案，但他们尚未回复。这些状态在 Arch 中很少使用，但应该更频繁地使用。尽管如此，重要的是您要关注缺陷（请参阅#投票和关注），因为开发人员或缺陷查找者通常会在评论中提出问题。
已请求任务关闭 - 这不完全是一个状态，但您可能会发现一些带有此类通知的缺陷报告。这表明有人请求关闭缺陷。大多数情况下，请求中会添加原因。由分配的开发人员决定他们是否接受关闭。
已关闭 - 要么这不是有效的缺陷（请参阅#不属于缺陷的原因），要么已找到并发布解决方案。

缺陷管理员负责分派缺陷并设置其状态，并与打开缺陷所针对的软件包的各自维护者一起提供帮助。