實作新功能¶

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

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

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

貢獻新功能¶

建立開發環境

要為 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 分成可以獨立檢閱的多個部分，或記錄一個問題，以便其他人可以調查並解決問題。

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

實作新功能

Fixing a bug or implementing a feature will require you to write some new code.

We have a code style guide that outlines our guidelines for writing code for BeeWare.

Test-driven development¶

A good way to ensure your code is going to do what you expect it to, is to first write a test case to test for it. This test case should fail initially, as the code it is testing for is not yet present. You can then write the code changes needed to make the test pass, and know that what you've written is solving the problem you are expecting it to.

Run your code¶

Once your code is written, you need to ensure it runs. You'll need to manually run your code to verify it is doing what you expect. If you haven't already, you'll want to write a test case for your changes; as mentioned above, this test should fail if your code is commented out or not present.

You'll add your test case to the test suite, so it can be run alongside the other tests. The next step is to run the test suite.

Running tests and coverage¶

BeeWare uses tox to manage the testing process and pytest for its own test suite.

The default tox command includes running:

pre-commit hooks
towncrier release note check
documentation linting
test suite for available Python versions
code coverage reporting

This is essentially what is run by CI when you submit a pull request.

To run the full test suite, run:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

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

The full test suite can take a while to run. You can speed it up considerably by running tox in parallel, by running tox p (or tox run-parallel). When you run the test suite in parallel, you'll get less feedback on the progress of the test suite as it runs, but you'll still get a summary of any problems found at the end of the test run. You should get some output indicating that tests have been run. You may see SKIPPED tests, but shouldn't ever get any FAIL or ERROR test results. We run our full test suite before merging every patch. If that process discovers any problems, we don't merge the patch. If you do find a test error or failure, either there's something odd in your test environment, or you've found an edge case that we haven't seen before - either way, let us know!

In addition to the tests passing, this should report 100% test coverage.

Running test variations¶

Run tests for multiple versions of Python¶

By default, many of the tox commands will attempt to run the test suite multiple times, once for each Python version supported by BeeWare. To do this, though, each of the Python versions must be installed on your machine and available to tox's Python discovery process. In general, if a version of Python is available via PATH, then tox should be able to find and use it.

Run only the test suite¶

If you're rapidly iterating on a new feature, you don't need to run the full test suite; you can run only the unit tests. To do this, run:

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

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

Run a subset of tests¶

By default, tox will run all tests in the unit test suite. When you're developing your new test, it may be helpful to run just that one test. To do this, you can pass in any pytest specifier as an argument to tox. These test paths are relative to the briefcase directory. For example, to run only the tests in a single file, run:

macOSLinuxWindows

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

You'll still get a coverage report when running a part of the test suite - but the coverage results will only report the lines of code that were executed by the specific tests you ran.

Run the test suite for a specific Python version¶

By default tox -e py will run using whatever interpreter resolves as python on your machine. If you have multiple Python versions installed, and want to test a specific Python version from the versions you have installed, you can specify a specific Python version to use. For example, to run the test suite on Python 3.10, run:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

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

A subset of tests can be run by adding -- and a test specification to the command line.

Run the test suite without coverage (fast)¶

By default, tox will run the pytest suite in single threaded mode. You can speed up the execution of the test suite by running the test suite in parallel. This mode does not produce coverage files due to complexities in capturing coverage within spawned processes. To run a single python version in "fast" mode, run:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

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

A subset of tests can be run by adding -- and a test specification to the command line; a specific Python version can be used by adding the version to the test target (e.g., py310-fast to run fast on Python 3.10).

Code coverage¶

BeeWare maintains 100% branch coverage in its codebase. When you add or modify code in the project, you must add test code to ensure coverage of any changes you make.

However, BeeWare targets multiple platforms, as well as multiple versions of Python, so full coverage cannot be verified on a single platform and Python version. To accommodate this, several conditional coverage rules are defined in the tool.coverage.coverage_conditional_plugin.rules section of pyproject.toml (e.g., no-cover-if-is-windows can be used to flag a block of code that won't be executed when running the test suite on Windows). These rules are used to identify sections of code that are only covered on particular platforms or Python versions.

Of note, coverage reporting across Python versions can be a bit quirky. For instance, if coverage files are produced using one version of Python but coverage reporting is done on another, the report may include false positives for missed branches. Because of this, coverage reporting should always use the oldest version Python used to produce the coverage files.

Understanding coverage results¶

At the end of the coverage test output there should be a report of the coverage data that was gathered:

Name    Stmts   Miss Branch BrPart   Cover   Missing
----------------------------------------------------
總計 7540 0 1040 0 100.0% 0

This tells us that the test suite has executed every possible branching path in the code. This isn't a 100% guarantee that there are no bugs, but it does mean that we're exercising every line of code in the codebase.

If you make changes to the codebase, it's possible you'll introduce a gap in this coverage. When this happens, the coverage report will tell you which lines aren't being executed. For example, lets say we made a change to some/interesting_file.py, adding some new logic. The coverage report might look something like:

姓名 Stmts Miss Branch BrPart 封面缺失
--------------------------------------------------------------------------------
src/some/interesting_file.py 111 1 26 0 98.1% 170, 302-307, 320->335
--------------------------------------------------------------------------------
總計 7540 1 1726 0 99.9

This tells us that line 170, lines 302-307, and a branch jumping from line 320 to line 335, are not being executed by the test suite. You'll need to add new tests (or modify an existing test) to restore this coverage.

Coverage report for host platform and Python version¶

You can generate a coverage report for your platform and version of Python. For example, to run the test suite and generate a coverage report on Python 3.10, run:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

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

Coverage report for host platform¶

If all supported versions of Python are available to tox, then coverage for the host platform can be reported by running:

macOSLinuxWindows

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

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

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

Coverage reporting in HTML¶

A HTML coverage report can be generated by appending -html to any of the coverage tox environment names, for instance:

macOSLinuxWindows

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

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

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

It's not just about writing tests!¶

Although we ensure that we test all of our code, the task isn't just about maintaining that level of testing. Part of the task is to audit the code as you go. You could write a comprehensive set of tests for a concrete life jacket… but a concrete life jacket would still be useless for the purpose it was intended!

As you develop tests, you should be checking that the core module is internally consistent as well. If you notice any method names that aren't internally consistent (e.g., something called on_select in one module, but called on_selected in another), or where the data isn't being handled consistently, flag it and bring it to our attention by raising a ticket. Or, if you're confident that you know what needs to be done, create a pull request that fixes the problem you've found.

///

/// details-abstract | 建立文件

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



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

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

### 即時文件預覽

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

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

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

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

///

啟動即時伺服器：



/// tab | macOS



```console
(venv) $ tox -e docs-live

LinuxWindows

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