如何撰写好的 issue

当您在使用 Hugging Face 库时遇到似乎不正确的地方，您绝对应该告知我们，以便我们能够修复它（对于任何开源库来说也是如此）。如果您不完全确定 bug 是在您自己的代码中还是在我们的库中，首先要检查的地方是论坛。社区将帮助您弄清楚这一点，Hugging Face 团队也密切关注那里的讨论。

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

创建最小可复现示例

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

一旦您有了自包含的内容，您可以尝试将其减少到更少的代码行，构建我们所说的最小可复现示例。虽然这需要您付出更多努力，但如果您提供一个简洁明了的 bug 复现器，您几乎肯定会获得帮助和修复。

如果您感觉足够舒适，请检查 bug 发生的源代码。您可能会找到解决问题的方法（在这种情况下，您甚至可以建议一个 pull request 来修复它），但更普遍的是，这可以帮助维护人员在阅读您的报告时更好地理解源代码。

填写 issue 模板

当您提交 issue 时，您会注意到有一个模板需要填写。我们将在此处遵循 🤗 Transformers issues 的模板，但如果您在另一个仓库中报告 issue，则需要相同类型的信息。不要将模板留空：花时间填写它将最大程度地提高您获得答案和解决问题的机会。

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

包含您的环境信息

🤗 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 命令的开头添加一个 !，以从 notebook 单元格执行它，然后复制粘贴结果到您的 issue 的开头。

@ 某人

通过键入 @ 后跟他们的 GitHub 句柄来 @ 某人将向他们发送通知，以便他们看到您的 issue 并可能更快地回复。适度使用此功能，因为您 @ 的人可能不喜欢在与他们没有直接联系的情况下收到通知。如果您查看了与您的 bug 相关的源文件，您应该 @ 最后在该行进行更改的人，您认为该行是造成您问题的原因（您可以通过在 GitHub 上查看该行，选择它，然后单击“查看 git blame”来找到此信息）。

否则，模板会提供要 @ 哪些人的建议。一般来说，永远不要 @ 超过三个人！

包含可复现示例

如果您已成功创建一个自包含的示例来复现 bug，现在是时候包含它了！键入一行带有三个反引号，后跟 python，像这样

```python

然后粘贴您的最小可复现示例，并键入一个新行，其中包含三个反引号。这将确保您的代码格式正确。

如果您没有设法创建可复现的示例，请用清晰的步骤解释您是如何遇到 issue 的。如果可以，请包含指向您遇到错误的 Google Colab notebook 的链接。您分享的信息越多，维护人员就越能更好地回复您。

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

描述预期行为

用几行文字解释您期望得到什么，以便维护人员充分理解问题。这部分通常很明显，所以应该可以用一句话概括，但在某些情况下，您可能有很多话要说。

接下来呢？

一旦您的 issue 被提交，请确保快速检查一切看起来是否正常。如果您犯了错误，您可以编辑 issue，如果您意识到问题与您最初的想法不同，甚至可以更改其标题。

如果您没有得到回复，那么 ping 人是没有意义的。如果几天内没有人帮助您，则可能是没有人理解您的问题。不要犹豫，回到可复现的示例。您可以使其更短更切中要点吗？如果您在一周内没有得到回复，您可以礼貌地留言请求帮助，尤其是在您编辑了 issue 以包含有关问题的更多信息之后。