如何编写一个好的 Issue

当您发现 Hugging Face 某个库出现问题时，您应该立即告知我们，以便我们进行修复（对于任何开源库都是如此）。如果您不完全确定问题出在您的代码还是我们的库中，第一个要检查的地方是论坛。社区会帮助您解决这个问题，Hugging Face 团队也会密切关注那里的讨论。

当您确定自己遇到了一个错误时，第一步是构建一个最小可复现示例。

创建最小可复现示例

隔离产生错误的代码片段非常重要，因为 Hugging Face 团队中没有人是魔术师（目前还没有），他们无法修复他们看不到的东西。最小可复现示例应该，顾名思义，是可复现的。这意味着它不应该依赖您可能拥有的任何外部文件或数据。尝试将您正在使用的数据替换为一些看起来像您真实数据的虚拟值，并且仍然产生相同的错误。

一旦您有了自包含的代码，您可以尝试将其缩减为更少的代码行，从而构建我们称之为*最小可复现示例*的东西。虽然这需要您付出更多努力，但如果您提供一个清晰、简短的 bug 复现器，您几乎肯定会得到帮助和修复。

如果您足够自信，请检查您的 bug 发生处的源代码。您可能会找到解决您问题的方法（在这种情况下，您甚至可以提交拉取请求来修复它），但更一般地，这可以帮助维护者在阅读您的报告时更好地理解源代码。

填写 Issue 模板

当您提交 issue 时，您会注意到有一个模板需要填写。我们将在此处遵循Hugging Face Transformers issue 的模板，但如果您在其他仓库报告 issue，也需要提供类似的信息。不要留空模板：花时间填写它会最大程度地增加您获得答案和解决问题的机会。

一般来说，提交问题时，请始终保持礼貌。这是一个开源项目，因此您正在使用免费软件，没有人有义务帮助您。您可以在问题中包含您认为合理的批评，但维护者可能会因此感到不快，并且不会急于帮助您。请务必阅读项目的行为准则。

包含您的环境信息

Hugging Face Transformers 提供了一个实用程序来获取我们需要的所有环境信息。只需在您的终端中输入以下命令：

transformers-cli env

您应该会看到类似以下内容：

Copy-and-paste the text below in your GitHub issue and FILL OUT the two last points.

- `transformers` version: 4.12.0.dev0
- Platform: Linux-5.10.61-1-MANJARO-x86_64-with-arch-Manjaro-Linux
- Python version: 3.7.9
- PyTorch version (GPU?): 1.8.1+cu111 (True)
- Tensorflow version (GPU?): 2.5.0 (True)
- Flax version (CPU?/GPU?/TPU?): 0.3.4 (cpu)
- Jax version: 0.2.13
- JaxLib version: 0.1.65
- Using GPU in script?: <fill in>
- Using distributed or parallel set-up in script?: <fill in>

您还可以在 `transformers-cli env` 命令的开头添加一个 `!`，以便从笔记本单元格中执行它，然后将结果复制粘贴到您的 issue 的开头。

标记人员

通过键入 `@` 加上他们的 GitHub 句柄来标记人员，这将向他们发送通知，以便他们会看到您的问题并可能更快地回复。请适度使用，因为如果您标记的人与问题没有直接关联，他们可能会不喜欢收到通知。如果您查看了与您的错误相关的源文件，您应该标记您认为导致您问题的行上最后一次进行更改的人（您可以通过在 GitHub 上查看该行、选择它，然后单击“View git blame”来找到此信息）。

否则，模板提供了标记人员的建议。一般来说，不要标记超过三个人！

包含可复现示例

如果您已经成功创建了一个可以复现错误的独立示例，现在是时候把它包含进去了！输入一行三个反引号，后面跟着 `python`，像这样：

```python

然后粘贴您的最小可复现示例，再输入一个新行，同样是三个反引号。这将确保您的代码格式正确。

如果您未能创建可复现示例，请清楚地解释您是如何遇到问题的。如果可以的话，附上您遇到错误的 Google Colab 笔记本链接。您分享的信息越多，维护者就越能回复您。

在所有情况下，您都应该复制并粘贴您收到的完整错误消息。如果您在 Colab 中工作，请记住堆栈跟踪中有些帧可能会自动折叠，因此请确保在复制之前展开它们。与代码示例一样，将错误消息放在两行三个反引号之间，以便正确格式化。

描述预期行为

用几行文字解释您期望得到的结果，以便维护者能够完全理解问题。这部分通常非常明显，所以应该用一句话概括，但在某些情况下您可能有很多话要说。

然后呢？

提交问题后，请务必快速检查一切是否正常。如果您犯了错误，可以编辑问题，甚至可以更改其标题，如果您意识到问题与您最初想象的不同。

如果您没有得到回复，请不要反复催促。如果几天内没有人帮助您，很可能没有人能理解您的问题。请毫不犹豫地回到可复现示例。您能把它写得更短、更切中要点吗？如果一周内没有得到回复，您可以礼貌地留言寻求帮助，特别是如果您已编辑问题以包含更多有关问题的信息。