如何撰寫有效的 Issue

當您遇到 Hugging Face 庫中某些不正確的地方時，您絕對應該告訴我們，以便我們能夠修復它（對於任何開源庫來說都是如此）。如果您不完全確定錯誤是否出在您自己的程式碼或我們的某個庫中，首先要檢查的地方是論壇。社群將幫助您弄清楚這一點，Hugging Face 團隊也會密切關注那裡的討論。

當您確定自己遇到錯誤時，第一步是構建一個最小的可復現示例。

建立最小的可復現示例

隔離產生錯誤的程式碼片段非常重要，因為 Hugging Face 團隊中還沒有人會魔法，他們無法修復他們看不到的東西。一個最小的可復現示例，顧名思義，應該是可復現的。這意味著它不應依賴於您可能擁有的任何外部檔案或資料。嘗試用一些看起來像真實資料但仍然會產生相同錯誤的虛擬值替換您正在使用的資料。

🚨 🤗 Transformers 儲存庫中的許多問題都未解決，因為用於復現它們的資料無法訪問。

一旦您擁有了自包含的內容，您可以嘗試將其減少到更少的程式碼行，構建我們稱之為最小可復現示例的內容。雖然這需要您多做一些工作，但如果您提供一個簡潔、簡短的錯誤復現程式，幾乎可以保證獲得幫助和修復。

如果您感覺足夠自信，請檢查發生錯誤的原始碼。您可能會找到解決問題的方法（在這種情況下，您甚至可以建議一個拉取請求來修復它），但更普遍地說，這可以幫助維護者在閱讀您的報告時更好地理解原始碼。

填寫 Issue 模板

當您提交 Issue 時，您會注意到有一個模板需要填寫。我們將遵循 🤗 Transformers 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 並可能更快地回覆。適度使用此功能，因為您標記的人員可能不希望在與他們沒有直接關聯的事情上收到通知。如果您查看了與您的錯誤相關的原始檔，則應標記在您認為導致您問題的行中最後進行更改的人員（您可以透過在 GitHub 上檢視該行，選擇它，然後單擊“檢視 git 責任”來找到此資訊）。

否則，模板會提供要標記人員的建議。一般來說，永遠不要標記超過三個人！

包含可復現示例

如果您已設法建立一個產生錯誤的自包含示例，那麼現在是時候包含它了！鍵入一行，其中包含三個反引號後跟 python，如下所示

```python

然後貼上您的最小可復現示例，並鍵入一個包含三個反引號的新行。這將確保您的程式碼格式正確。

如果您未能建立可復現示例，請清楚地說明您是如何遇到該問題的。如果可以，請提供一個指向您遇到錯誤的 Google Colab 筆記本的連結。您分享的資訊越多，維護者就越能夠回覆您。

在所有情況下，您都應該複製並貼上您遇到的完整錯誤訊息。如果您在 Colab 中工作，請記住堆疊跟蹤中的一些框架可能會自動摺疊，因此請確保在複製之前展開它們。與程式碼示例一樣，將錯誤訊息放在兩行三反引號之間，以便正確格式化。

描述預期行為

用幾句話解釋您期望得到什麼，以便維護人員能夠全面瞭解問題。這部分通常非常明顯，因此應該用一句話概括，但在某些情況下，您可能需要說很多話。

然後呢？

提交問題後，請務必快速檢查所有內容是否正常。如果您犯了錯誤，可以編輯問題，或者如果您意識到問題與您最初的想法不同，甚至可以更改其標題。

如果您沒有得到回覆，就沒有必要ping其他人。如果幾天內沒有人幫助您，則可能沒有人能夠理解您的問題。不要猶豫，回到可復現的示例。您能否使其更短、更切中要害？如果一週內沒有收到回覆，您可以留下訊息，禮貌地尋求幫助，尤其是在您編輯了問題以包含更多有關問題的資訊時。

NLP 課程