缺陷报告指南

在 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...）
- 在控制台中运行您的程序，并在可用时使用详细和/或调试模式（请参阅您的程序文档），并将输出复制到文件中。在终端中运行应用程序时，请确保相关信息以英文显示，以便更多人可以理解。这可以通过使用 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 中很少使用，但应更频繁地使用。尽管如此，您关注缺陷非常重要（请参阅 #投票和关注），因为开发人员或缺陷查找人员通常会在评论中提出问题。
已请求任务关闭 - 这不完全是状态，但您可能会发现一些带有此类通知的缺陷报告。这表明有人请求关闭缺陷。大多数情况下，请求中都会添加原因。是否接受关闭取决于受让人开发人员。
已关闭 - 要么这不是有效的缺陷（请参阅 #不是缺陷的原因），要么已找到并发布解决方案。

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