缺陷报告指南

在 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 package_name 或使用网站）并查看上游 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 允许您向软件包添加评论，您应该使用这些评论向软件包维护者报告缺陷。

标题

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

以下是一些建议

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

严重性

本文或章节已过时。

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

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

以下是严重性的一般用法

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

包含相关信息

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

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

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

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

跟进缺陷

不要认为报告缺陷后工作就完成了!

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

投票和关注

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

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

回复额外信息请求

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

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

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

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

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

解决后关闭

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

缺陷状态

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

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

缺陷管理员负责分派缺陷并设置其状态，并得到缺陷所针对的软件包的各自维护者的帮助。