缺陷报告指南

在 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 报告指南中讨论）

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

以下是严重性的一般用法

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

包含相关信息

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

关于报告错误的优秀教程可以在 https://www.chiark.greenend.org.uk/~sgtatham/bugs.html 找到。

但是，开发人员或错误猎手会在需要时向您索取更多信息。幸运的是，在提交几个错误报告后，您就会知道应该提供哪些信息。

简短的信息可以内联在您的错误报告中，而长信息（日志、截图...）应该作为附件。

跟进错误

不要认为报告错误后工作就完成了!

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

投票和关注

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

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

回复额外的信息请求

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

请花时间在被要求时提供更多信息，并尝试建议的解决方案.

如果您在几周或一个月后不回答问题，开发人员或错误猎手将关闭您的错误。

当新的软件包版本发布时更新错误报告

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

解决后关闭

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

错误状态

在其生命周期中，错误可能会经历几个状态

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

Bug Wranglers 负责分派错误并设置其状态，并与错误针对的软件包的各自维护者一起提供帮助。