跳轉到

修復問題

BeeWare 會追蹤 [已知問題] 的清單 (https://github.com/search?q=org%3Abeeware%20is%3Aopen%20is%3Aissue%20label%3Abug&type=issues)。任何這些問題都是候選項目。

此清單可以各種方式篩選。例如，您可以依平台篩選，這樣您就可以專注於影響您能夠測試的平台的問題；也可以依問題類型篩選，例如 documentation bugs。還有一個 [good first issues] 的過濾器(https://github.com/search?q=org%3Abeeware+is%3Aopen+is%3Aissue+label%3Abug+label%3A%22good+first+issue%22&type=issues） - 這些都是已經被確認為有已知原因的問題，而且我們相信修復應該會比較直接（雖然我們的分析可能有誤）。

如果問題已超過 6 個月，則該問題完全有可能已經解決，因此第一步是驗證您是否可以重現該問題。使用錯誤回報中提供的資訊嘗試重現問題。如果您無法重現問題，請以問題評論的方式報告您所發現的問題，並選擇其他問題。

如果您可以重現問題 - 請嘗試修正它！找出實現該功能的程式碼組合，看看是否能找出哪些部分無法正確運作。

即使您無法修復問題，報告您在過程中發現的任何東西，作為對問題的評論也是值得的。如果您能找到問題的來源，但卻找不到修復方法，這些知識通常就足以讓更瞭解平台的人解決問題。如果問題尚未提供良好的重現案例 (一個除了重現問題之外什麼都不做的小型範例應用程式)，提供一個案例可以提供很大的幫助。

貢獻問題修正

建立開發環境

要為 BeeWare 做出貢獻，您必須建立開發環境。

先決條件

您需要安裝下列先決條件。

BeeWare 需要 Python 3.10+ 。您也需要一個管理虛擬環境的方法 (例如 venv)。

您可以執行 Python 來驗證已安裝的 Python 版本：

Python 3.8.10 (預設版，2020年7月20日 16:16:00)

如果您安裝了多個版本的 Python，您可能需要將 python3 改為特定的版本號 (例如，python3.13)

我們建議避免使用最近釋出的 Python 版本 (也就是有「.0」或「.1」微版本號的版本，例如 3.14.0)。這是因為在 macOS 上支援 Python 所需的工具經常會滯後，通常無法在最近釋出的 Python 穩定版本上使用。

BeeWare 需要 Python 3.10+ 。您也需要一個管理虛擬環境的方法 (例如 venv)。

您可以執行 Python 來驗證已安裝的 Python 版本：

Python 3.8.10 (預設版，2020年7月20日 16:16:00)

如果您安裝了多個版本的 Python，您可能需要將 python3 改為特定的版本號 (例如，python3.13)

我們建議避免使用最近釋出的 Python 版本 (也就是有「.0」或「.1」微型版本號的版本，例如 3.14.0)。這是因為在 Linux 上支援 Python 所需的工具經常會滯後，通常無法在最近釋出的 Python 穩定版本上使用。

BeeWare 需要 Python 3.10+ 。您也需要一個管理虛擬環境的方法 (例如 venv)。

您可以執行 Python 來驗證已安裝的 Python 版本：

C:\...>py -3 --version

如果您安裝了多個版本的 Python，您可能需要將 -3 改為特定的版本號 (例如，-python3.13)

我們建議避免使用最近釋出的 Python 版本 (也就是有「.0」或「.1」微版本號的版本，例如 3.14.0)。這是因為在 Windows 上支援 Python 所需的工具經常會滯後，通常無法在最近釋出的 Python 穩定版本上使用。

設定您的開發環境

為 BeeWare 設定開發環境的建議方式是使用 虛擬環境，然後安裝 BeeWare 的開發版本及其相依性。

複製 BeeWare 儲存庫

接下來，前往 GitHub 上的 BeeWare 頁面，如果還沒有，請 fork 儲存庫 到您自己的帳戶。接下來，點擊您的 fork 上的「<>程式碼」按鈕。如果您的電腦上安裝了 GitHub 桌面應用程式，您可以選擇「用 GitHub 桌面打開」；否則，複製所提供的 HTTPS URL，然後用它來使用命令行將倉庫複製到您的電腦上：

分叉 BeeWare 儲存庫，然後：

$ git clone https://github.com/<您的使用者名稱>/beeware.git

(用您的 GitHub 用戶名代替）

分叉 BeeWare 儲存庫，然後：

$ git clone https://github.com/<您的使用者名稱>/beeware.git

(用您的 GitHub 用戶名代替）

分叉 BeeWare 儲存庫，然後：

C:\...>git clone https://github.com/<您的使用者名稱>/beeware.git

(用您的 GitHub 用戶名代替）

設定上游儲存庫

複製您的分支後，將 BeeWare 儲存庫新增為 upstream 遠端。此操作使您的本地複製本能參照原始儲存庫，便於後續同步更新。

您還需要從 upstream 取得標籤，以便 Toga 和 Briefcase 等工具能解析精確的版本號碼：

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

C:\...>git remote add upstream https://github.com/beeware/beeware.git
C:\...>git fetch --tags upstream

若您希望您的分支也包含這些標籤，可以將它們推送：

$ git push --tags

若您日後創建新的克隆版本，並希望從您的分支中使用標籤，此操作將有所助益。

建立虛擬環境

若要設定虛擬環境並升級 pip，請執行：

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

C:\...>cd beeware
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) $ python -m pip install -U pip

現在，您的提示前應該有(.venv)前綴。

安裝 {{ 正式名稱 }}

現在您有了原始碼，就可以將 BeeWare 的 editable install 安裝到您的開發環境中。執行以下指令：

(.venv) $ python -m pip install -U -e . --group dev

(.venv) $ python -m pip install -U -e . --group dev

(.venv) C:\...>python -m pip install -U -e . --group dev

啟用預先提交

BeeWare 使用一個叫做 pre-commit 的工具來識別簡單的問題，並標準化程式碼格式。它透過安裝一個 git 鉤子，在任何 git commit 定稿之前，自動執行一系列的程式碼處理器。要啟用 pre-commit，請執行

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) C:\...>pre-commit install
pre-commit installed at .git/hooks/pre-commit

現在您可以開始入侵 BeeWare 了！

從分支工作

在您開始進行變更之前，請確定您已建立分支。預設情況下，當您克隆您的 repository fork 時，您會在您的 main 分支上 check out。這是 BeeWare 的 main 分支的直接複本。

雖然您可以從您的main分支提交拉取請求，但最好不要這樣做。如果您提交的拉取請求幾乎*正確，審閱您的拉取請求的核心團隊成員可能就能做出必要的變更，而不是給予回饋要求做小的變更。但是，如果您從您的「主」分支提交您的拉取請求，審閱者就無法進行修改。

在您完成第一個 pull request 之後，在您的主分支上工作也會對您*造成困難。如果您想進行第二次拉取請求，您需要有一份上游專案主分支的「乾淨」複本，作為您第二次貢獻的基礎；如果您已經從您的「主」分支進行了第一次貢獻，您就不再有這個乾淨的版本可用。

相反，您應該在 * 功能分支*上進行變更。功能分支有一個簡單的名稱來識別您所做的變更。例如，如果您要修正一個會導致 Windows 11 上建立問題的 bug，您可以建立一個功能分支 fix-win11-build。如果您的錯誤與已報告的特定問題有關，通常也會在分支名稱中提及該問題編號 (例如 fix-1234)。

若要建立「fix-win11-build」功能分支，請執行：

(.venv) $ git switch -c fix-win11-build

(.venv) $ git switch -c fix-win11-build

(.venv) C:\...>git switch -c fix-win11-build
重現問題

如果一開始就沒有問題，就無法解決問題。因此，重現問題是修復問題的先決條件。在軟體中，問題通常被稱為 "bug「，而問題通常被稱為 」bug 報告"。

有人提供了錯誤報告。您需要驗證報告人所描述的步驟是否會導致所報告的錯誤。您是否可以完全按照報告中的描述重現相同的結果？如果不能，您需要找出原因。

程式碼中的錯誤

在理想的情況下，您會擁有與回報錯誤的人相同的設定，您會遵循步驟，並能夠重現所述的錯誤。但在很多情況下，這並不是那麼簡單。許多 bug 報告只包含含糊的解釋，以及一組含糊的條件。問題是，許多 bug 會根據所涉及的一系列條件而有所不同，包括與它們互動的方式、各種先決條件、作業系統、作業系統版本、CPU 架構，或使用者的機器是又舊又慢還是又新又快。對於圍繞錯誤的情況，我們掌握的資訊越多越好。嘗試重現報告者提供的一系列情況。如果您無法這樣做，下一步可能需要向回報錯誤的人索取更多資訊。

重現錯誤的最佳方式是使用仍能顯示問題的最小範例。大多數情況下，報告者不會提供最小的可行範例；如果他們提供任何範例，都是直接從他們的「真實世界」應用程式中複製出來的。您的目標是將報告縮減到能顯示問題的最簡單形式。最好的重現案例就是最小的程式。這種還原本身就很有幫助，因為它可以決定實際的問題是什麼。任何人都可以使用最小的範例，執行它，他們就會觀察到所描述的錯誤。

文件中的錯誤

文件中的錯誤可能有不同的表現方式。有些是格式上的問題，會導致呈現問題。有時候，這甚至不是一個錯誤；有關人員可能誤讀了文件，或是真的犯了一個錯誤。這不一定表示文件沒有問題。內容可能不清楚或不精確，留下混淆或誤解的空間。也有可能應該討論的概念沒有討論，因為它完全沒有文件記載。

當文件問題的 bug 被歸檔時，您會想要確認所報告的問題是否真的仍然存在。如果是渲染問題，您需要建立文件，看看是否可以重現問題。內容問題則需要閱讀以確認是否有人提交更新。

更新問題

分流程序的最後一步是在問題上留下評論，以記錄您的發現。

如果您能夠完全依照所描述的方式重現問題，這就是您需要說的。請留下評論，說明您已確認您看到相同的問題，而且與原始報告者所描述的方式完全相同。

如果您能夠提供任何額外的背景，請包含該背景的詳細資訊。這可能包括能夠在不同的作業系統上重現問題，或使用某些相關軟體的不同版本，或任何其他與原始報告不同的地方。

如果原始報告遺漏了重現報告所需的詳細資訊，請包含*這些詳細資訊。這可能包括提供原始報告沒有提供的作業系統或版本詳細資訊、更完整的日誌或堆疊追蹤，或更清楚的指示重現問題所需的確切操作順序。如果您已經開發出重製問題的更簡單方法 (或原始報告者沒有提供重製案例)，您可以包含該重製方法的詳細資訊。

若您無法重現該問題，也請留下評論說明您嘗試過的解決步驟。了解問題不存在的位置與存在的位置同樣重要，這有助於縮小可能的成因範圍。 若您對無法重現問題的原因有任何推測——例如認為是使用方式錯誤，或近期作業系統更新已解決此問題——請將這些推論一併納入留言說明。

最後，您可以向核心團隊提出任何建議。如果您認為原始報告有誤，建議應該關閉此問題；如果您對問題的成因有自己的看法，也可以提出建議。您的意見將有助於核心團隊找出如何將問題推進到下一步。

如果修復問題需要變更程式碼：

編寫、執行及測試程式碼

要修復錯誤或實作新功能，您將需要撰寫一些新程式碼。

我們有一份 程式碼風格指南，其中概述了為 BeeWare 編寫程式碼的準則。

測試驅動開發

確保程式碼能如預期運作的好方法，是先撰寫一個測試案例來驗證它。這個測試案例最初應該會失敗，因為它所測試的程式碼尚未存在。接著，您可以撰寫必要的程式碼變更以讓測試通過，並確信您所寫的程式碼確實解決了您預期要解決的問題。

執行您的程式碼

寫完程式碼後，您需要確保它能夠執行。您必須手動執行程式碼，以驗證其運作結果是否符合預期。若尚未進行，建議您為所做的變更撰寫測試案例；如前所述，若程式碼被註解掉或不存在，此測試應會失敗。

您將把測試案例新增至測試套件中，以便它能與其他測試一併執行。下一步是執行該測試套件。

執行測試 及覆蓋率

BeeWare 使用 tox 來管理測試流程，並使用 pytest 來管理其自身的測試套件。

預設的 tox 指令包含執行：

  • 預提交鉤子
  • towncrier 版本說明檢查

  • 文件檢查

  • 適用於各 Python 版本的測試套件

  • 程式碼覆蓋率報告

這基本上就是您提交拉取請求時，CI 所執行的流程。

若要執行完整的測試套件，請執行：

(.venv) $ tox

(.venv) $ tox

(.venv) C:\...>tox

執行完整的測試套件可能需要一段時間。您可以透過並行執行 tox，或執行 tox p（或 tox run-parallel）來大幅加快速度。當您並行執行測試套件時，在執行過程中獲得的進度回報會較少，但測試執行結束後仍會收到任何發現問題的摘要。您應該會看到一些輸出訊息，顯示測試已執行。 您可能會看到 SKIPPED 個測試，但絕不應收到任何 FAIL 或 ERROR 的測試結果。我們會在合併每個修補程式之前執行完整的測試套件。若該過程發現任何問題，我們便不會合併該修補程式。如果您確實發現測試錯誤或失敗，那可能是您的測試環境有異常，或是您發現了我們尚未遇過的邊界案例——無論是哪種情況，請務必告知我們！

除了測試通過之外，這應該會顯示 100% 測試覆蓋率。

執行測試變體

針對多個 Python 版本執行測試

預設情況下，許多 tox 指令會嘗試多次執行測試套件，針對 BeeWare 所支援的每個 Python 版本執行一次。不過，要達成此目的，您的電腦上必須已安裝每個 Python 版本，且 tox 的 Python 偵測 程序能夠找到這些版本。一般來說，如果 PATH 能偵測到某個 Python 版本，那麼 tox 應該就能找到並使用它。

僅執行測試套件

如果您正在對新功能進行快速迭代，則無需執行完整的測試套件；您可以僅執行單元測試。要執行此操作，請執行：

(.venv) $ tox -e py

(.venv) $ tox -e py

(.venv) C:\...>tox -e py

執行部分測試

預設情況下，tox 會執行單元測試套件中的所有測試。當您開發新測試時，可能需要「僅」執行該單一測試。要達成此目的，您可以將 任何 pytest 指定符 作為參數傳遞給 tox。這些測試路徑是相對於 briefcase 目錄的。例如，若要僅執行單一檔案中的測試，請執行：

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) C:\...>tox -e py -- tests/path_to_test_file/test_some_test.py

即使只執行測試套件的一部分，您仍會收到覆蓋率報告——但覆蓋率結果僅會顯示您所執行的特定測試所執行的程式碼行。

執行特定 Python 版本的測試套件

預設情況下，tox -e py 會使用您電腦上解析為 python 的任何解釋器來執行。如果您安裝了多個 Python 版本，且希望從已安裝的版本中測試特定版本，您可以指定要使用的特定 Python 版本。例如，若要在 Python 3.10 上執行測試套件，請執行：

(.venv) $ tox -e py310

(.venv) $ tox -e py310

(.venv) C:\...>tox -e py310

若要在命令列中加入 -- 以及測試規格，即可執行 測試子集。

不包含覆蓋率的測試套件（快速）

預設情況下，tox 會以單執行緒模式執行 pytest 測試套件。您可以透過並行執行測試套件來加快執行速度。由於在子程序中擷取覆蓋率較為複雜，此模式不會產生覆蓋率檔案。若要以「快速」模式執行單一 Python 版本，請執行：

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

(.venv) C:\...>tox -e py-fast

若要在命令列中執行 測試子集，請在命令列中加入 -- 以及測試規格；若要使用 特定的 Python 版本，請在測試目標中加入該版本（例如，加入 py310-fast 以在 Python 3.10 上執行 fast）。

程式碼覆蓋率

BeeWare 的程式碼庫維持 100% 的分支覆蓋率。當您在專案中新增或修改程式碼時，必須新增測試程式碼，以確保所做的任何變更都能獲得測試覆蓋。

然而，BeeWare 同時支援多個平台以及多個 Python 版本，因此無法僅在單一平台和 Python 版本上驗證完整覆蓋率。 為此，在 tool.coverage.coverage_conditional_plugin.rules 的 pyproject.toml 區段中定義了數個條件性覆蓋率規則（例如，可使用 no-cover-if-is-windows 標記在 Windows 上執行測試套件時不會被執行的程式碼區塊）。這些規則用於識別僅在特定平台或 Python 版本上被覆蓋的程式碼區段。

值得注意的是，不同 Python 版本之間的覆蓋率報告可能會有些許差異。例如，若使用某個版本的 Python 產生覆蓋率檔案，卻在另一個版本上進行報告，報告中可能會出現因分支遺漏而產生的誤報。因此，進行覆蓋率報告時，應始終採用產生覆蓋率檔案時所使用的最舊版本 Python。

理解承保結果

在覆蓋率測試輸出的結尾處，應包含一份關於所收集覆蓋率數據的報告：

名稱    報表   缺失分支   分支比例   覆蓋率   缺失
 ---------------------------------------------------
 總計    7540 0   1040 0  100.0%

這告訴我們，測試套件已經執行了程式碼中所有可能的分支路徑。這雖不能百分之百保證沒有錯誤，但確實意味著我們已經測試了程式碼庫中的每一行程式碼。

如果您對程式碼庫進行修改，可能會導致此覆蓋率出現缺口。一旦發生這種情況，覆蓋率報告會告訴您哪些程式碼行未被執行。例如，假設我們對 some/interesting_file.py 進行了修改，新增了一些邏輯。覆蓋率報告可能會顯示如下內容：

名稱 陳述式   缺失 分支 分支部分  覆蓋率   缺失
 -------------------------------------------------------------------------------
 src/some/interesting_file.py 111 1     26 0  98.1%   170, 302-307, 320->335
 -------------------------------------------------------------------------------
 總計 7540 1     1726 0  99.9%

這表示第 170 行、第 302 至 307 行，以及從第 320 行跳轉至第 335 行的分支，均未被測試套件執行。您需要新增測試（或修改現有測試）以恢復此處的程式碼覆蓋率。

主機平台與 Python 版本的覆蓋率報告

您可以針對您的平台和 Python 版本產生覆蓋率報告。例如，若要執行測試套件並針對 Python 3.10 產生覆蓋率報告，請執行：

(.venv) $ tox -m test310

(.venv) $ tox -m test310

(.venv) C:\...>tox -m test310

主機平台覆蓋報告

如果 tox 可用於所有受支援的 Python 版本，則可透過執行以下指令來報告主機平台的覆蓋率：

(.venv) $ tox p -m test-platform

(.venv) $ tox p -m test-platform

(.venv) C:\...>tox p -m test-platform

HTML 中的報導範圍

只要在任何覆蓋率 -html 環境名稱後面加上 tox，即可產生 HTML 覆蓋率報告，例如：

(.venv) $ tox -e coverage-platform-html

(.venv) $ tox -e coverage-platform-html

(.venv) C:\...>tox -e coverage-platform-html

這不只是關於撰寫測試！

雖然我們確保會測試所有程式碼，但這項任務並非僅僅在於維持這樣的測試水準。任務的一部分在於邊開發邊審查程式碼。你可以為一件「混凝土製救生衣」編寫一套完整的測試用例……但那件「混凝土製救生衣」對於其原本的用途來說，依然毫無用處！

在開發測試時，您也應確認核心模組在內部是否一致。 若您發現任何方法名稱在內部不一致（例如，某個模組中名為 on_select，但在另一個模組中卻稱為 on_selected），或是資料處理方式不一致，請標記該問題並透過建立工單向我們通報。或者，如果您確信知道該如何處理，請建立拉取請求來修正您發現的問題。

如果修正問題需要變更文件：

建立文件

在對 BeeWare 的文件進行任何變更之前，確認您可以建立現有的文件是很有幫助的。

您 ** 必須** 在路徑上安裝 Python 3.13 譯器，並且可以使用 (也就是說， python3.13 必須啟動 Python 3.13 譯器)。

BeeWare 使用 tox 建立文件。以下的 tox 指令必須從與 tox.ini 檔相同的位置執行，也就是專案的根目錄。

即時文件預覽

為了支援文件的快速編輯，BeeWare 具有「即時預覽」模式。

即時預覽將伴隨警告訊息進行建構！

Live serve 可供您迭代文件更新。在更新的過程中，您可能會引入標記問題。被視為「警告」的問題會導致標準建立失敗，然而，即時服務的設定會在控制台輸出中顯示警告，同時繼續建立。這允許您迭代，而不需要重新啟動即時預覽。

警告」與「錯誤」不同。如果您引入了被視為 ERROR 的問題，即時服務就會失敗，並需要重新啟動。在 WARNING 問題解決之前，它不會再次啟動。

啟動即時伺服器：

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

(venv) C:\...>tox -e docs-live

這將會建立文件、啟動 Web 伺服器以提供文件，並觀察檔案系統對文件來源的任何變更。

伺服器啟動後，您會在主控台輸出中看到類似以下的內容：

資訊    -  [11:18:51] 伺服器位於 http://127.0.0.1:8000/

開啟瀏覽器，並導航至所提供的 URL。現在您可以開始迭代文件。如果偵測到變更，文件將會重建，任何檢視修改後頁面的瀏覽器都會自動重新整理。

docs-live` 是一個初步的步驟

執行 docs-live 來使用 Live 伺服器是用來進行初始迭代的。在提交拉取請求之前，您應該 ** 執行本地建立。

本地建置

一旦完成迭代，您就需要在本地建立文件。如果有任何標記問題，這個建立過程會失敗。這可讓您捕捉任何您在 Live 伺服器上可能遺漏的問題。

產生本地建立

若要產生本地建立：

(venv) $ tox -e docs

(venv) $ tox -e docs

(venv) C:\...>tox -e docs

此建立的輸出將會在專案根目錄的 _build 目錄中。

產生本地翻譯的建立檔

BeeWare 的說明文件已翻譯為多種語言。英文文件的更新有可能導致其他語言版本的問題。在提交拉取請求之前，請務必確認所有的建立版本都正常運作。

要產生所有可用翻譯的建立檔：

(動詞) $ tox -e docs-all

(動詞) $ tox -e docs-all

(venv) C:\...>tox -e docs-all

每種語言的建立輸出會在相關的 _build/html/<languagecode> 目錄中，其中 <languagecode> 是與特定語言相關的 2 個或 5 個字元的語言代碼 (例如 fr 代表法文、it 代表義大利文等)。

如果您發現單一建立有問題，您可以執行 tox -e docs-<languagecode> 來分別執行該單獨建立。例如，若要只建立法文文件，請執行：

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

(venv) C:\...>tox -e docs-fr

單一語言建立的輸出將會在 _build 目錄中。

文件整理

建立過程會找出 Markdown 的問題，但 BeeWare 會執行一些額外的樣式與格式檢查，稱為「linting」。執行 lint 檢查：

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

(venv) C:\...>tox -e docs-lint

這將驗證文件不包含：

  • 死超連結
  • 拼字錯誤

如果一個單字的有效拼法被識別為拼錯，則將該單字加入 docs/spelling_wordlist 中的清單。這將會把該單字加入拼字檢查器的字典中。加入此清單時，請記住：

  • 我們偏好美式拼法，但對於程式特定的口語（例如「apps」）和名詞的動詞（例如「scrollable」）則有一些自由度。
  • 任何對產品名稱的引用都應該使用該產品名稱的首字母大寫。(例如，"macOS"、"GTK"、"pytest"、"Pygame"、"PyScript"）。
  • 如果一個詞語是 「作為代碼 」使用的，那麼它應該被引用為字面意義（like this），而不是被添加到字典中。
撰寫文件

以下是為 BeeWare 撰寫文件貢獻的步驟。

更新現有文件

如果您要編輯現有的說明文件，您需要在 /docs/en 目錄中找到該檔案。檔案結構遵循頁面結 構，因此您可以使用說明文件 URL 來定位檔案。

新增文件

如果您要新增一個新文件，還需要一些步驟。

您需要在 docs/en 目錄中的適當位置建立文件。為了方便討論，我們假設您要新增一個文件名為 new_doc.md的新文件。

然後，您需要更新 docs/en/SUMMARY.md 檔案，以包含您的新檔案。SUMMARY.md 的組織基本上反映了 docs/en 目錄的結構，但更重要的是，它直接決定了左側欄的結構。如果您找到打算包含 new_doc.md 的部分，如果看到列出的通配符路徑，您不需要在 SUMMARY.md 中做任何修改。例如

- ./路徑/至/目錄/*

如果您打算包含 new_doc.md 的部分是個別 Markdown 連結的清單，您就需要在您的部分加入明確的連結。例如

- [我的新文件](new_doc.md)

撰寫您的文件

現在您可以在編輯器中開啟所需的檔案，並開始撰寫。

我們有一份 文件風格指南，概述了我們為 BeeWare 撰寫文件的準則。

當您準備好提交您的貢獻時：

新增變更備註

許多BeeWare工具使用towncrier來協助建立每個版本的發行紀錄。當您提交一個拉取請求給其中一個適用的工具時，它將需要包含一個變更備註 - 這個變更備註將成為發行記錄中描述所做變更的項目。

每個 pull request 必須在 changes/ 目錄中包含至少一個檔案，提供該 pull request 所執行變更的簡短說明。變更說明應該使用 Markdown 格式，檔案名稱格式為 <id>.<fragment type>.md。如果您提出的變更會修復一個 bug 或實作一個現有問題編號的功能，ID 就是該票據的編號。如果變更沒有對應的問題，則可以使用 PR 編號作為 ID。在您推送拉取請求之前，您不會知道這個 PR 編號，所以第一次 CI 傳送會無法通過 towncrier 檢查；新增變更備註並推送 PR 更新，CI 應該就會通過。

共有五種片段類型：

  • 特性」：PR 增加了以前無法實現的新行為或功能（例如，增加對新封裝格式的支援，或在現有封裝格式中增加新功能）；
  • bugfix：PR 修正了現有實作中的一個 bug；
  • doc：PR 是對文件的重大改進；
  • 刪除」； PR 代表 BeeWare 中向後不相容的變更。API; 或
  • misc; 輕微或管理性的變更（例如修正錯字、輕微的語言澄清，或更新依賴版本），不需要在發行公告中公佈。

變更筆記中的描述應該是從使用者的角度對變更的高層次「行銷」摘要，而不是深入的技術描述或實作細節。它有別於提交訊息 - 提交訊息會說明已經做了什麼，以便未來的開發人員可以了解變更的原因；變更說明則是為了使用者的利益而做的說明，因為使用者可能不了解內部的情況。

例如，如果您修正了與專案命名相關的錯誤，提交訊息可能會寫成

套用更強的正則表達式檢查，禁止使用以數字開頭的專案名稱。

相應的變更備忘錄內容如下：

專案名稱不能再以數字開頭。

有些 PR 會引入多項功能並修復多個錯誤，或引入多項向後不相容的變更。在這種情況下，PR 可能有多個變更備註檔。如果需要將兩個片段類型與相同的 ID 聯繫起來，可以附加一個數字後綴。例如，如果 PR 789 增加了 ticket 123 所描述的功能，關閉了 ticket 234 所描述的錯誤，還做了兩項向後不相容的變更，您可能會有 4 個變更備註檔案：

  • 123.feature.md
  • 234.bugfix.md
  • 789.removal.1.md
  • 789.removal.2.md

更多關於 towncrier 和片段類型的資訊，請參閱 News Fragments。您也可以在 BeeWare 儲存庫的 changes 目錄中查看現有的新聞片段範例。如果這個資料夾是空的，很可能是因為 BeeWare 最近發行了新版本；每次發行時，都會刪除變更備註檔，並合併更新 release notes 。您可以查看該檔案，瞭解所需的注釋樣式；您可以查看 recently merged PRs 來瞭解變更備註的格式。

提交拉取請求

現在您已提交所有變更，您已準備好提交拉取請求。為了確保您的審核過程順利，您應該採取一些步驟。

使用預先提交

當您提交任何變更時，pre-commit 會自動執行。如果在提交過程中發現任何問題，這將導致您的提交失敗。在可能的情況下，pre-commit 會進行所需的變更來修正它所發現的問題。在下面的例子中，ruff 檢查發現了一個代碼格式問題：

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) C:\...>git add some/interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

在這種情況下，ruff會自動修正問題；因此您可以重新加入任何因為預提交檢查而被修改的檔案，並重新提交變更。然而，有些檢查需要您手動修改。一旦您做了這些修改，請重新新增任何修改過的檔案，並重新提交。

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) C:\...>git add some\interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

一旦一切都通過了，您會看到一則提示提交已完成的消息，而您的 git 日誌也會顯示您的提交是最近新增的。現在您可以推送到 GitHub 了。

將您的變更推送至 GitHub 並建立您的拉取請求

當您第一次推送到 GitHub 時，系統會提供一個 URL，讓您直接前往 GitHub 頁面建立新的拉取請求。按照 URL 創建您的拉取請求。

以下顯示了在 push 時的範例，並高亮顯示 URL。

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) C:\...>git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

如果您之前已將目前的分支推送到 GitHub，就不會再收到這個 URL。不過，還有其他方法可以取得 PR 建立 URL：

  • 導覽到上游套件庫，點選「Pull Requests」，接著點選 「New pull request」，然後選擇您要提交拉取請求的套件庫。
  • 如果您最近有推送，請導航至上游套件庫，找到檔案清單上方顯示該套件庫「最近有推送」的橫幅，然後按一下「比較與拉取請求」按鈕。
  • 使用 GitHub CLI gh pr create 指令，並填寫提示內容。
  • 使用 GitHub CLI gh pr create --web 指令開啟網頁瀏覽器，進入 PR 建立頁面。

任何這些選項都能讓您建立新的拉取請求。

GitHub 命令列介面：gh

GitHub 提供了 GitHub CLI，讓你可以在終端透過 gh 命令使用 GitHub 的許多功能。GitHub CLI 文件](https://cli.github.com/manual/) 涵蓋了所有的功能。

拉取請求內容

拉取請求的標題必須內容豐富、清晰、簡潔。如果可能的話，盡量保持簡短，但如果需要的話，較長的標題也是可以接受的。一個好的 PR 標題應該讓沒有任何上下文的人有一個合理確切的概念，知道您的 PR 實作了什麼 bug 或功能。

PR 描述必須清楚反映 PR 中的變更。一個沒有任何背景的人應該可以閱讀您的說明，並相對完整地瞭解為何要進行變更。避免使用笑話、成語、口語和不必要的格式，例如使用大寫或過多的標點符號；這應該是對您的 PR 中發生的事情的直接說明，避免這些事情會讓其他人更容易理解您的說明。

如果有任何重現案例或您使用的任何測試方案尚未成為 PR 中變更的一部分，則應該在 PR 中加以說明和包含。解釋內容應包括如何執行這些測試，以及如何重製所需結果。

如果您的拉取請求將解決問題 #1234，您應該在拉取請求的描述中包含文字 Fixes #1234。這將使問題在拉取請求被合併時自動關閉。您可以使用相同的 #1234 語法參照其他討論、問題或拉取請求。您可以參考不同套件庫上的問題，在編號前加上前綴 - 例如 python/cpython#1234 將指 CPython 套件庫上的問題 1234。

持續整合

持續整合，或 CI，是對您的 pull request 執行自動檢查的過程。這可能包括簡單的檢查，例如確保程式碼格式正確；但也包括執行測試套件和建立文件。

有許多變更可能導致 CI 失敗。一般而言，我們不會審核未通過 CI 的 PR。如果您創建了一個 pull request，但 CI 失敗了，我們不會開始您的審核，直到它通過為止。如果您的變更導致失敗，您有責任調查原因並解決問題。

當 CI 失敗時，失敗連結會顯示在 PR 頁面底部，標題為「某些檢查未成功」。您會看到失敗檢查的清單，如果還有通過的檢查，則會顯示在所有檢查清單的頂端。如果您按一下失敗連結，它會帶您到日誌。日誌通常會提供您找出失敗原因所需的所有資訊。閱讀日誌並嘗試找出故障發生的原因，然後採取必要的措施來解決問題。

CI 檢查偶爾會因為與您的變更無關的原因而失敗。這可能是因為執行 CI 檢查的機器出現問題，或是因為 CI 檢查不穩定。如果您看到失敗，而且相當確定與您的變更無關，請在您的 PR 中加入相關註解，我們會進行調查。

若要觸發新的 CI 執行，您需要將新變更推送到您的分支。

如果您發現自己處於需要協助讓 CI 通過的情況，請在 PR 上留言讓我們知道，我們會盡力提供協助。

pre-commit」和「towncrier」檢查

如果「pre-commit」或「towncrier」檢查失敗，就會阻擋大部分其他 CI 檢查的執行。您需要先解決適用的問題，才能執行全套檢查。

我們的 CI 資源有限。重要的是要了解，每次您推送到分支時，CI 都會啟動。如果您要進行多次變更，最好在本機進行這些變更，一次推送完成。CI 只會在批次中最新的提交上執行，將我們 CI 系統的負載降到最低。

在您的 PR 通過 CI，或您能提供解釋為何不通過 CI 之前，提交 PR 的程序才算完成。