跳轉到

提交新問題

撰寫一份好的問題或錯誤報告，對於排除故障的能力有很大的幫助。以下是如何向 BeeWare 提交一份好的錯誤報告。

搜尋現有問題

在提交新問題之前，請在索引中搜尋與您問題相符的現有問題。如果現有的開放問題似乎與您的問題相符，請在該問題上新增註解，並提供有關您經驗的任何其他資訊。例如，如果您是在不同的 Python 版本或不同的作業系統上看到問題，這些額外的資訊可能有助於判斷問題的影響或原因。

如果您發現已關閉的問題似乎與您的問題相符，請檢查該問題最近關閉的時間。如果該問題是最近關閉的，這可能表示您的錯誤已被修正，並將在下一個版本中修正。如果該問題是在 4 個月前關閉的，那麼您所遇到的很可能是另一個問題 - 無論錯誤訊息看起來有多相似。

如果您沒有找到與您所看到的相符的問題，開啟一個新問題可能會比較合適。

從討論開始

在 GitHub 上提交問題之前，請考慮先從討論開始，詢問您所遇到的實際上是否是一個 bug，或是您的設定或流程上的問題。除非您看到的行為直接與文件中的行為相衝突，否則在直接提交 bug 報告之前，應該先提出問題。如果您發現了一個問題，討論主題很容易就會變成問題。

開始討論也可以確保您在最合適的地方回報問題。儘管您可能在使用 BeeWare 時遇到問題，但問題可能是由 BeeWare 生態系統中不同專案的錯誤所導致。

撰寫一份好的錯誤報告

如果**需要一個新的問題，提供盡可能多的細節是很重要的。一份好的錯誤回報包含所有可能與錯誤相關的資訊，以及最小可能的重現範例。

複製範例應該盡可能簡短扼要，同時仍能顯示出錯誤。提供龐大的範例會顯著增加疑難排解的難度，尤其是當範例依賴於其他函式庫，或需要廣泛了解範例的預期行為或內部邏輯時。

我們需要您提供盡可能多的詳細資料。這包括，但絕不局限於：

  • 您的作業系統版本 - 細至微型版本 (例如：macOS 15.7.2)。
  • 您的 Python 版本，也可細至微型版本 (例如 3.14.1)。
  • 您如何安裝 Python。您是從 python.org 下載的？您使用 Homebrew 嗎？uv?pyenv？conda？其他的？
  • 您使用的 BeeWare 工具的特定版本（例如 Toga 0.5.3）。如果您使用的是開發版本，您使用的 Git 雜湊是多少？只說 「目前的主分支 」是不夠的，因為這可能每天都在變化。
  • 必須安裝才能觸發問題的其他套件的特定版本。您可以包含執行 python -m pip freeze 的結果來提供此資訊。
  • 如果已產生記錄檔，*整個記錄檔。
  • 如果已產生堆疊追蹤，請提供完整的堆疊追蹤。不要只提供最終的錯誤訊息 - 堆疊追蹤的完整內容非常重要。最好以文字格式提供，而不是截圖。
  • 您的電腦或網路設定是否有其他可能影響問題的因素。您的電腦是否較舊或較慢？工作用的電腦是否有防火牆、病毒檢查器或其他限制？您的網路速度是否特別慢？您是否使用不尋常的系統預設值來執行作業系統 (例如啟用超大字型或其他輔助技術)？

嘗試跳出框框思考，將您能想到的、可能影響您所遇到的問題的所有東西都包括在內。如果您給我們的比我們需要的還要多，我們就很容易忽略我們不需要的東西。我們無法想出您遺漏的東西。

最小範例

錯誤報告中最重要的部分是最基本的重現案例。第三者應該可以閱讀您重現案例的說明、遵循這些說明，並觀察到相同的問題。這可能意味著提供一個顯示問題的範例專案 - 或者，更好的是，使用一個已存在的範例 (例如現有程式碼庫中的教學或範例專案)。

您的完整專案***不是最小重現案例。最小重現案例不應該包含任何不是製造問題所絕對需要的程式碼。在撰寫重現案例時要嚴謹 - 如果製造問題不需要按鈕，就不要包含該按鈕。

很多時候，開發這個最小複製案例的過程會揭露問題的根源，因為建立最小範例的行為會迫使您找出問題的確切原因，不論是程式碼中的 bug，或是源自不正確的假設或 API 使用。

您也應該在任何重製指示中**明確。說「關閉範例應用程式」可能是指按一下視窗上的關閉按鈕、從選單中選擇「退出」或在終端輸入 Control-C。您的報告應該在重現問題所需執行的步驟上不留任何含糊不清的空間。

提交報告

導航至 專案問題清單，點擊「新增問題」按鈕，並選擇「錯誤回報」以開始流程。

您必須填寫問題範本中的 ** 所有部分。** 我們提供範本作為提示，以協助您提供必要的資訊。請記住，您可以（也應該！）提供比範本要求更多的資訊，但我們至少需要範本中的所有資訊。

當包含程式碼時，如果您可以使用現有的範例重現程式碼，例如 BeeWare 教學，您可以提供一個連結。否則，請在報告中提供程式碼。請使用 Markdown 格式；代碼塊前後需要三個反撇號 (````)。

如果您需要包含較長的文字區塊，可以使用下列語法使其成為折疊內容：

<details>
<summary>Collapsed content title</summary>
Long block of text.
</details>

提供盡可能多的資訊後，按一下「建立」以提交報告。