提交拉取請求¶

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

使用預先提交¶

當您提交任何變更時，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 的程序才算完成。

您的拉取請求可能需要補充內容（例如[變更說明]），方能進行[審查]。