使用工具

我們所能獲得的最有價值的反饋之一，就是人們在嘗試使用BeeWare工具的過程中，發現了一些摩擦點或缺少的功能。了解您在實際使用BeeWare工具時可能遇到的困難對我們來說是非常有用的。

想一想您一直想建造的東西，然後嘗試建造它。如果結果證明您能夠完成您的專案，恭喜您！您擁有了一直想要的東西。

但是，如果您沒有成功，請讓我們知道哪裡出了問題。是否有遺漏的功能？文件是否有混亂或欠缺的地方？分享您的經驗能給我們有用的啟發，我們可以利用這些啟發來塑造我們的規劃流程。

如果您遇到任何問題，請開始一個新的討論主題，因為這可能是一個新問題或功能提案的開始。

貢獻工具的使用

提交新問題

撰寫一份好的問題或錯誤報告，對於排除故障的能力有很大的幫助。以下是如何向 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>

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

提出新功能

您對 {{ 正式名稱 }} 有了改進的想法。- 您該如何提交該想法以供考慮？

進行研究

第一步是搜尋 BeeWare 問題追蹤器中現有的 feature issues (標示為「enhancement」的問題), documentation issues (issues tagged "documentation")，或 Discussion threads 看看這個想法之前是否有人提過。如果有，而且您有新的背景或想法要補充，請將它們包含在現有的主題中。如果您在研究過程中需要協助，您可以在 BeeWare Discord 的 #dev channel 中詢問。我們或許能夠為您指出現有主題的方向，提供您可能不知道的背景，或將您的想法與另一個可能看起來沒有立即關聯的想法連結起來。

討論想法

如果您沒有找到任何與您的構想相關的現有參考資料，請開始一個 討論主題.提供您的想法的目的和用例的高層級描述。包含您對該功能實作後的外觀的任何想法，例如 API 的一般形狀、功能的視覺外觀，或將新增的文件。如果適用的話，您也應該包含您對於您的想法在不同平台上的表現所做的任何研究。

一旦討論主題被開啟，BeeWare團隊和社群的其他成員將會回應。核心團隊的目標是在兩個工作天內對您的想法提供至少一個初步印象。如果一個想法特別複雜，更詳細的分析可能需要一個星期。假日和會議等活動可能會導致這些時間略微延長。

這是您參與有關構想對話的機會。我們可能會詢問更多細節或背景。社區的其他成員也可能參與討論，提供其他觀點、建議或反提案。討論結果將決定下一步的步驟。

重要的是要了解並非所有的想法都會被接受。這個過程之所以從提案開始，是為了避免您投入了所有的工作，卻發現您的變更不被接受是有原因的。

這並不表示這不是個好主意！可能有技術上的原因導致無法實現。例如，我們可能會拒絕一個想法，如果：

• 難以或不可能在所有支援的平台上可靠地執行；或
• 難以維護，或維護需要使用尚未普及的技術或軟體；或
• 它服務的是利基受眾，但對其他使用者造成顯著的開銷。

如果我們認為您的想法不適合，這並不表示您應該放棄。雖然我們可能會拒絕某個*特定的想法，但我們可能會更樂意加入外掛介面或其他延伸點，讓您可以維護與外部函式庫相同的功能。這樣您就可以擁有這個功能，但不會因為特定的維護問題或功能限制而對專案本身造成束縛。

轉換為正式的功能請求

一旦討論就功能的形式達成共識，您就可以在 BeeWare 問題追蹤中，建立一個新的 feature request issue 來總結討論內容，並連結到討論的上下文。

您不一定要自己實作您的功能提案；您可以開啟一個包含您提案內容細節的問題。然而，單單張貼問題並不代表它會為您實作。您需要等待它有可能被其他對相同功能有興趣的人採納，無論那是指其他社群成員或核心團隊；但這並不保證一定會發生。如果您想要保證實作，您需要自己實作，或是付錢給其他人替您實作。