修復問題¶

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 做出貢獻，您必須建立開發環境。

先決條件¶

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

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

重現問題

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

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

程式碼中的錯誤¶

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

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

文件中的錯誤¶

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

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

更新問題¶

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

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

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

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

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

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

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

編寫、執行及測試程式碼

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