如何編寫一個好的 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 中工作，請記住堆疊跟蹤中有些幀可能會自動摺疊，因此請確保在複製之前展開它們。與程式碼示例一樣，將錯誤訊息放在兩行三個反引號之間，以便正確格式化。

描述預期行為

用幾行文字解釋您期望得到的結果，以便維護者能夠完全理解問題。這部分通常非常明顯，所以應該用一句話概括，但在某些情況下您可能有很多話要說。

然後呢？

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

如果您沒有得到回覆，請不要反覆催促。如果幾天內沒有人幫助您，很可能沒有人能理解您的問題。請毫不猶豫地回到可復現示例。您能把它寫得更短、更切中要點嗎？如果一週內沒有得到回覆，您可以禮貌地留言尋求幫助，特別是如果您已編輯問題以包含更多有關問題的資訊。