8-How_to_ask_for_help-4-How_to_write_a_good_issue

中英文对照学习，效果更佳！
原课程链接：https://huggingface.co/course/chapter8/5?fw=pt

How to write a good issue

如何写好一期杂志

When you encounter something that doesn’t seem right with one of the Hugging Face libraries, you should definitely let us know so we can fix it (the same goes for any open source library, for that matter). If you are not completely certain whether the bug lies in your own code or one of our libraries, the first place to check is the forums. The community will help you figure this out, and the Hugging Face team also closely watches the discussions there.

在Studio Lab中的Colab Open中提出问题当您遇到某个Hugging Face库出现问题时，您绝对应该让我们知道，这样我们就可以修复它(任何开源库都是如此)。如果您不能完全确定错误是存在于您自己的代码中还是存在于我们的某个库中，那么首先要检查的地方是论坛。社区会帮你弄清楚这一点，Hugging Face团队也密切关注那里的讨论。

When you are sure you have a bug in your hand, the first step is to build a minimal reproducible example.

当您确定手中有一个错误时，第一步是构建一个最小的可重现的示例。

Creating a minimal reproducible example

创建一个最小的可重现示例

It’s very important to isolate the piece of code that produces the bug, as no one in the Hugging Face team is a magician (yet), and they can’t fix what they can’t see. A minimal reproducible example should, as the name indicates, be reproducible. This means that it should not rely on any external files or data you may have. Try to replace the data you are using with some dummy values that look like your real ones and still produce the same error.

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

🚨 Many issues in the 🤗 Transformers repository are unsolved because the data used to reproduce them is not accessible.

🚨🤗Transformer存储库中的许多问题都未得到解决，因为用于复制这些问题的数据不可访问。

Once you have something that is self-contained, you can try to reduce it into even less lines of code, building what we call a minimal reproducible example. While this requires a bit more work on your side, you will almost be guaranteed to get help and a fix if you provide a nice, short bug reproducer.

一旦有了自包含的东西，就可以尝试将其减少到更少的代码行，构建我们所称的最小可重现示例。虽然这需要您做更多的工作，但如果您提供一个很好的、简短的错误复制器，您几乎可以保证得到帮助和修复。

If you feel comfortable enough, go inspect the source code where your bug happens. You might find a solution to your problem (in which case you can even suggest a pull request to fix it), but more generally, this can help the maintainers better understand the source when they read your report.

如果您觉得足够舒服，那么就去检查一下发生错误的源代码。您可能会找到问题的解决方案(在这种情况下，您甚至可以建议一个拉请求来修复它)，但更一般的情况下，这可以帮助维护人员在阅读您的报告时更好地理解来源。

Filling out the issue template

填写问题模板

When you file your issue, you will notice there is a template to fill out. We will follow the one for 🤗 Transformers issues here, but the same kind of information will be required if you report an issue in another repository. Don’t leave the template blank: taking the time to fill it in will maximize your chances of getting an answer and solving your problem.

当您提交您的问题时，您会注意到有一个模板需要填写。我们将在这里遵循🤗Transformer问题的信息，但如果您在另一个存储库中报告问题，将需要相同类型的信息。不要把模板留空：花时间填写它会最大限度地增加你获得答案和解决问题的机会。

In general, when filing an issue, always stay courteous. This is an open source project, so you are using free software, and no one has any obligation to help you. You may include what you feel is justified criticism in your issue, but then the maintainers may very well take it badly and not be in a rush help you. Make sure you read the code of conduct of the project.

一般来说，在提交问题时，始终保持礼貌。这是一个开源项目，所以您使用的是自由软件，没有人有任何义务帮助您。您可能会在您的问题中包含您认为合理的批评，但维护人员很可能会很不高兴地接受它，而不是急于帮助您。确保您阅读了项目的行为准则。

Including your environment information

包括您的环境信息

🤗 Transformers provides a utility to get all the information we need about your environment. Just type the following in your terminal:

🤗Transformers提供了一个实用程序来获取我们需要的有关您的环境的所有信息。只需在您的终端中键入以下内容：

transformers-cli env

and you should get something like this:

你应该得到这样的东西：

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>

You can also add a ! at the beginning of the transformers-cli env command to execute it from a notebook cell, and then copy and paste the result at the beginning of your issue.

您也可以在Transformers-cli env命令的开头添加！，从笔记本单元格执行该命令，然后将结果复制粘贴到您的问题的开头。

Tagging people

为用户添加标签

Tagging people by typing an @ followed by their GitHub handle will send them a notification so they will see your issue and might reply quicker. Use this with moderation, because the people you tag might not appreciate being notified if it’s something they have no direct link to. If you have looked at the source files related to your bug, you should tag the last person that made changes at the line you think is responsible for your problem (you can find this information by looking at said line on GitHub, selecting it, then clicking “View git blame”).

通过在GitHub账号后面输入@来标记用户，会给他们发送通知，这样他们就会看到你的问题，并可能会更快地回复。适度地使用这一点，因为你标记的人可能不会喜欢被通知，如果他们没有直接链接的话。如果你已经看过与你的错误相关的源文件，你应该在你认为对你的问题负责的那一行上标记最后一个做出更改的人(你可以通过在GitHub上查看这一行，选择它，然后点击“查看git指责”来找到这一信息)。

Otherwise, the template offers suggestions of people to tag. In general, never tag more than three people!

否则，模板会提供要标记的人的建议。一般来说，永远不要给三个以上的人贴标签！

Including a reproducible example

包括一个可复制的例子

If you have managed to create a self-contained example that produces the bug, now is the time to include it! Type a line with three backticks followed by python, like this:

如果您已经成功地创建了一个生成该错误的自包含示例，那么现在是时候将其包括在内了！键入一行带有三个反号的行，后跟python，如下所示：

```python

then paste in your minimal reproducible example and type a new line with three backticks. This will ensure your code is properly formatted.

然后粘贴您最小的可重现示例，并键入带有三个反号的新行。这将确保您的代码格式正确。

If you didn’t manage to create a reproducible example, explain in clear steps how you got to your issue. Include a link to a Google Colab notebook where you got the error if you can. The more information you share, the better able the maintainers will be to reply to you.

如果你没有成功地创建一个可重复的例子，请清楚地解释你是如何解决问题的。如果可以的话，包括一个指向Google Colab笔记本的链接，在那里你得到了错误。您共享的信息越多，维护人员就越有能力回复您。

In all cases, you should copy and paste the whole error message you are getting. If you’re working in Colab, remember that some of the frames may be automatically collapsed in the stack trace, so make sure you expand them before copying. Like with the code sample, put that error message between two lines with three backticks, so it’s properly formatted.

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

Describing the expected behavior[[describing-the-expected-behavior]]

描述预期行为[[描述预期行为]]

Explain in a few lines what you expected to get, so that the maintainers get a full grasp of the problem. This part is generally pretty obvious, so it should fit in one sentence, but in some cases you may have a lot to say.

用几行文字解释一下您希望得到什么，这样维护人员就能充分了解问题。这一部分通常很明显，所以应该用一句话来表达，但在某些情况下，你可能有很多话要说。

And then what?[[and-then-what]]

然后呢？[然后-然后-什么]

Once your issue is filed, make sure to quickly check everything looks okay. You can edit the issue if you made a mistake, or even change its title if you realize the problem is different from what you initially thought.

一旦您的问题被归档，确保快速检查一切正常。如果你犯了一个错误，你可以编辑这个问题，甚至如果你意识到这个问题与你最初认为的不同，你可以修改它的标题。

There is no point pinging people if you don’t get an answer. If no one helps you in a few days, it’s likely that no one could make sense of your problem. Don’t hesitate to go back to the reproducible example. Can you make it shorter and more to the point? If you don’t get an answer in a week, you can leave a message gently asking for help, especially if you’ve edited your issue to include more information on the problem.

如果你得不到答案，给别人打电话是没有意义的。如果在几天内没有人帮助你，很可能没有人能理解你的问题。请不要犹豫，回到可重现的例子。你能把它缩短一些，切中要害吗？如果你在一周内没有得到答复，你可以留言，温和地寻求帮助，特别是如果你已经编辑了你的问题，包括了更多关于这个问题的信息。