新增文件

您可能擁有世界上最好的軟體，但如果沒人知道如何使用，那還有什麼意義？文件總是可以改進的 - 我們需要您的幫助！

文件表單

BeeWare 的文件是使用 MkDocs and Markdown 寫成的。我們的目標是遵循 Diataxis 架構文件。

Diataxis 架構描述了四種「形式」的文件：

• Tutorial - 有指導的學習經驗，有特定的專案終點。
• ** 方法指南** - 引導讀者達成特定目標或結果的說明。
• 主題指南 - 單一概念的討論，其解釋方式讓基本概念一目了然。
• ** 參考資料** - 特定 API 或其他介面的技術說明。

在開始任何文件貢獻之前，確定哪一種形式最適合是很重要的。許多文件提案一開始會被描述為要求「X 的教學」，但在大多數情況下，實際上需要的是如何操作、專題指南或改進的參考資訊。

舉例來說，您可以考慮撰寫有關烘烤餅乾的文件。

教學

教學是一種介紹，尤其是針對初學者的介紹，其目標應該是讓讀者從一個乾淨的起點到一個完成的產品。它需要非常具體的說明，以及將教學步驟放在上下文中的詳細解釋。您必須完全不假設讀者對於要說明的工具有任何經驗，雖然假設讀者對 Python 有一些基本的精通是合理的。

本教學應該包含定期的檢查點，讓讀者可以確定他們已經成功地完成了所描述的工作。在每個檢查點，都應該清楚說明成功的標準。應清楚概述已知的失敗案例，包括解釋讀者可能遇到的任何錯誤或問題。因讀者所採取的行動而改變的事情應該被指出來，即使看起來是顯而易見的。鼓勵重複說明，尤其是當您想要建立最佳實務或共同流程時。應避免解釋內部原理，也應避免解釋通往相同結果的其他路徑。

烘焙餅乾的教學不只是一份食譜。教學中的指示應該能讓從未烘焙過的人（例如小孩）看得懂，而且需要說明有經驗的烘焙師視為理所當然的事情，例如如何將糖和黃油乳化、預先加熱烤箱的過程，或是餅乾在食用前應該放置多久才會冷卻。教學的目的不是製作餅乾，而是傳達烘焙的基本知識。製作出來的餅乾才是說服人們一開始就參加教學的美味。

操作指南

使用指南應該著重於特定的實際案例和實際結果，而非理論上的解釋。與教學不同的是，您可以假設讀者對現有工具有一定的熟悉程度。讀者應該可以從頭到尾跟著指南來達到目標，但他們可能需要一些現有的知識才能做到。它應該包含一套具體的指示或邏輯步驟，需要遵循這些指示或步驟來達成指南的目標。

烹飪書中的食譜就是一個很好的指南範例。巧克力餅乾的食譜有很多，它們都有共同的特點，但任何特定的食譜都應該可以從頭到尾依循，並得到一致的結果。一份好的巧克力餅乾食譜不會牽涉到不同種類的糖或麵粉的相對優點，也不會詳細說明基本技術或流程；它只會包括烘焙一批餅乾的配料和說明，前提是讀者對烘焙有基本的認識。

主題指南

主題指南描述單一主題或概念。它可能包含範例程式碼或說明，但它更著重於提供整體概念的高層次圖像。它可能包含意見和其他觀點，但應該將重點放在指南的特定主題上。

烘焙餅乾的主題指南可能會深入探討餅乾作為烘焙產品的歷史、探討工業化製程所產生的餅乾種類與自製餅乾的不同，或是建議如何將餅乾納入均衡飲食中。如果您想烘焙餅乾，這本身不會是一份非常有用的文件，但它可能會提供一些背景資料，讓熟悉烘焙的人能夠成功地客製化現有的餅乾食譜。

參考資料

參考說明文件以資訊為導向，描述工具函式庫的操作細節。參考文件通常可以從程式碼本身產生，但好的 API 文件可能需要進一步的說明和上下文。雖然有時可能會包含使用範例，但應避免詳細說明。

烘焙參考指南可能會說明可以使用的糖的種類，並詳細說明它們在烘焙中使用時的特性。它可以描述有關糖的字面事實，但更廣泛地討論如何選擇不同種類的糖，則應該是如何使用或主題指南的主題。大部分包裝食品上的營養資訊都可視為參考文件。

文件樣式

BeeWare 的文件遵循 documentation style guide 中列出的指南。本指南包括基本風格和格式，以及拼字檢查的流程。它也涵蓋各種 Markdown 語法細節，例如參考連結語法、使用程式碼區塊的技巧，以及圖片處理。

貢獻文件

提出新文件

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

進行研究

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

討論想法

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

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

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

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

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

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

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

轉換為正式的功能請求

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

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

建立開發環境

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

先決條件

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

macOSLinuxWindows

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

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

$ python3 --version

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

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

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

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

$ python3 --version

如果您安裝了多個版本的 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，然後用它來使用命令行將倉庫複製到您的電腦上：

macOSLinuxWindows

分叉 BeeWare 儲存庫，然後：

$ git clone https://github.com/<your username>/beeware.git

(用您的 GitHub 用戶名代替）

分叉 BeeWare 儲存庫，然後：

$ git clone https://github.com/<your username>/beeware.git

(用您的 GitHub 用戶名代替）

分叉 BeeWare 儲存庫，然後：

C:\...>git clone https://github.com/<your username>/beeware.git

(用您的 GitHub 用戶名代替）

建立虛擬環境

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

macOSLinuxWindows

$ 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 安裝到您的開發環境中。執行以下指令：

macOSLinuxWindows

(.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，請執行

macOSLinuxWindows

(.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」功能分支，請執行：

macOSLinuxWindows

(.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 的文件進行任何變更之前，確認您可以建立現有的文件是很有幫助的。

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

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

即時文件預覽

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

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

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

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

啟動即時伺服器：

macOSLinuxWindows

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

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

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

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

INFO    -  [11:18:51] Serving on http://127.0.0.1:8000/

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

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

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

本地建置

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

產生本地建立

若要產生本地建立：

macOSLinuxWindows

(venv) $ tox -e docs

(venv) $ tox -e docs

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

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

產生本地翻譯的建立檔

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

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

macOSLinuxWindows

(venv) $ tox -e docs-all

(venv) $ tox -e docs-all

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

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

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

macOSLinuxWindows

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

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

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

文件整理

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

macOSLinuxWindows

(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 中做任何修改。例如

- ./path/to/directory/*

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

- [My new document](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 檢查發現了一個代碼格式問題：

macOSLinuxWindows

(.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會自動修正問題；因此您可以重新加入任何因為預提交檢查而被修改的檔案，並重新提交變更。然而，有些檢查需要您手動修改。一旦您做了這些修改，請重新新增任何修改過的檔案，並重新提交。

macOSLinuxWindows

(.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。

macOSLinuxWindows

(.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 的程序才算完成。