プルリクエストの送信

すべての変更をコミットしたところで、プルリクエストを送信する準備が整いました。スムーズなレビュープロセスを確保するため、いくつかの手順を踏む必要があります。

プレコミットとの連携

変更をコミットする際、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 log でそのコミットが最新の追加として確認できます。これで GitHub へのプッシュ準備が整いました。

変更を GitHub にプッシュし、プルリクエストを作成してください

GitHubに初めてプッシュすると、新しいプルリクエストを作成するためのGitHubページに直接移動するURLが提供されます。そのURLにアクセスしてプルリクエストを作成してください。

以下は、URLが強調表示された状態でpushに表示される内容の例です。

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にアクセスする他の方法があります：

• アップストリームリポジトリに移動し、「プルリクエスト」をクリックした後、「新しいプルリクエスト」を選択し、プルリクエストを送信したいブランチを選択してください。
• 最近プッシュした場合は、アップストリームリポジトリに移動し、ファイル一覧の上部に表示される「最近プッシュがあった」ことを示すバナーを見つけ、「比較してプルリクエスト」ボタンをクリックしてください。
• GitHub CLI gh pr create コマンドを使用し、プロンプトに従って入力してください。
• GitHub CLI gh pr create --web コマンドを使用して、PR作成ページにウェブブラウザを開きます。

これらのいずれかのオプションを選択することで、新しいプルリクエストを作成できます。

GitHub CLI: gh

GitHubはGitHub CLIを提供しており、これによりターミナルからghコマンドを通じてGitHubの多くの機能にアクセスできます。すべての機能についてはGitHub CLIドキュメントを参照してください。

プルリクエストの内容

プルリクエストのタイトルは、情報豊富で明確かつ簡潔である必要があります。可能な限り短く保つよう心がけましょう。ただし、必要に応じて長いタイトルも許容されます。優れたPRタイトルは、文脈を知らない人でも、そのPRでどのバグ修正や機能が実装されているかを十分に理解できるものでなければなりません。

プルリクエストの説明文は、PRの変更内容を明確に反映しなければなりません。文脈を知らない人が説明文を読んだだけで、変更の理由を比較的完全に理解できる必要があります。冗談、慣用句、口語表現、および大文字のみの使用や過剰な句読点といった不要な書式設定は避けてください。これはPRで何が起こっているかを率直に説明するものであり、こうした要素を排除することで説明文の理解しやすさが向上します。

PRに既に含まれていない再現ケースやテスト手順がある場合は、それらを説明しPRに含める必要があります。説明には、それらの実行方法と、望ましい結果を再現するための手順を含めるべきです。

プルリクエストが issue #1234 を解決する場合、プルリクエストの説明に Fixes #1234 というテキストを含める必要があります。これにより、プルリクエストがマージされると自動的に issue が閉じられます。他のディスカッション、issue、プルリクエストも同様の #1234 構文で参照できます。異なるリポジトリの issue を参照するには、番号の前に - を付加します。例えば python/cpython#1234 は CPython リポジトリの issue 1234 を指します。

継続的インテグレーション

継続的インテグレーション（CI）とは、プルリクエストに対して自動化されたチェックを実行するプロセスです。これには、コードが正しくフォーマットされていることを確認するといった単純なチェックが含まれますが、テストスイートの実行やドキュメントのビルドも含まれます。

CIの失敗を引き起こす変更は数多く存在します。大まかに言えば、CIを通過していないプルリクエストはレビューしません。プルリクエストを作成してCIが失敗した場合、通過するまでレビューを開始しません。変更が失敗の原因となった場合、その理由を調査し問題を解決するのはあなたの責任です。

CIが失敗した場合、失敗したリンクはPRページの下部、「一部のチェックが成功しませんでした」という見出しの下に表示されます。 失敗したチェックの一覧が表示され、合格したチェックがある場合でも、この失敗チェックは全チェックリストの最上部に表示されます。失敗リンクをクリックするとログが表示されます。ログには失敗の原因を特定するために必要な情報がほぼ全て記載されています。ログを読み込み、失敗の原因を特定した上で、必要な対応を行ってください。

時折、CIチェックが変更内容とは無関係な理由で失敗することがあります。これはCIチェックを実行するマシン側の問題、あるいはCIチェック自体が不安定であることが原因です。失敗を確認し、それが変更内容と無関係であると確信できる場合は、その旨をプルリクエストにコメントとして追加してください。調査いたします。

新しいCI実行をトリガーするには、ブランチに新しい変更をプッシュする必要があります。

CIを通過させるのに助けが必要な状況に陥った場合は、プルリクエストにコメントを残してその旨をお知らせください。できる限りのサポートをいたします。

pre-commit および towncrier チェック

pre-commit または towncrier のいずれかのチェックが失敗した場合、残りのほとんどの CI チェックの実行がブロックされます。チェックの全セットを実行するには、該当する問題を解決する必要があります。

CIリソースには限りがあります。ブランチにプッシュするたびにCIが開始されることを理解することが重要です。複数の変更を加える場合は、ローカルで変更を加え、まとめてプッシュすることをお勧めします。CIはバッチ内の最新コミットのみを実行するため、CIシステムへの負荷を最小限に抑えられます。

PRの提出プロセスは、CIを通過するか、または通過しない理由を説明できるまで完了しません。

プルリクエストは、[レビュー]を受ける前に、[変更内容の説明]などの追加情報が必要となる場合があります。