跳轉到

實作新功能

一旦 提案程序結束，您就應該有一個完整的新功能設計。這表示該開始撰寫了！

如果您的功能需要特定平台的實作，提案過程應該已經確認這個構想可以在所有平台上實作。但是，作為首次實作新功能的人，您並不負責在所有平台上實作新功能。您需要提供至少個平台的完整實作，包括測試。對於任何其他平台，您將需要提供一個「存根」實作 - 這個實作提供了完整的介面定義，但會產生「NotImplementedError」或輸出一則日誌訊息，說明該行為未在該平台上實作。

實作新功能的一個重要部分是確保該功能有完整的說明文件。這至少意味著要確保有 API 文件；但也可能需要新增操作指南或主題指南。

貢獻新功能

建立開發環境

要為 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
避免範圍蔓延

當單一貢獻所解決的問題或實現的功能清單大幅超出工作開始時的預期時，就會發生「範圍爬升」。您從一個簡單的問題開始；您發現了一個密切相關的問題，並決定也包含該修正；然後是第三個......在您知道之前，您已經有一個拉取請求，關閉了 5 個問題，並新增了 3 個功能，包括數十個檔案。

Scope creep 會發生在每個人身上。對於經驗豐富的開發人員而言，這是一個再熟悉不過的概念；我們都曾經多次發生過，並經歷過隨之而來的所有問題。

避免範圍擴大有非常實際的理由。貢獻越大，工作就越困難。識別邊緣案例或潛在問題變得更加困難，這意味著貢獻的整體品質可能會降低。當審查員需要處理多種可能毫無關聯的情況時，審查也會變得更具挑戰性。更大的貢獻意味著更多的審查評論，而身為貢獻者，跟蹤多個審查線程可能會變得很困難。甚至您的 GitHub 體驗也會受到影響 - GitHub 的使用者介面會隨著 PR 大小的增加而變慢，這意味著在 GitHub 介面上瀏覽檔案以及嘗試留下審閱評論會變得越來越困難。

任何時候，如果您發現有理由要在您的貢獻中加入任何東西，而這些東西並不是原始提案或錯誤報告中明確的一部分，您就應該考慮您是否正在邁向範圍爬升。是否有兩個不同的功能可以分開實作？一個功能是否可以在已知限制或錯誤的情況下實作，並在後續的拉取請求中修正該錯誤？錯誤修正的一部分是否獨立於另一部分？如果可以在不改變原始貢獻的情況下刪除變更的一部分，那就應該刪除。

開發軟體總是一個逐步改善的過程。每個人的貢獻都應該在合併後讓程式碼基礎處於更好的狀態，但留下錯誤或功能的一部分作為未來改進的工作也是完全可以接受的。這可能意味著將一個 pull request 分成可以獨立檢閱的多個部分，或記錄一個問題，以便其他人可以調查並解決問題。

限制每次貢獻的範圍有助於包括您在內的所有參與者。您的審稿人、甚至您自己，都會很感激。

實作新功能

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

我們有一份 程式碼風格指南，其中概述了為 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 的程序才算完成。