LLVM GitHub ユーザーガイド

はじめに

LLVMプロジェクトでは、ソースコード、リリース、問題追跡、コードレビューにGitHub を使用しています。ソースコード、リリース、問題トラッキング、コードレビュー。

このページでは、LLVMプロジェクトのユーザーと開発者がGitHubを使用してプロジェクトに参加する方法について説明します。

ブランチ

users/<username>/で始まるブランチを作成することは可能ですが、これは「スタックされた」プルリクエストをサポートするためのものであり、それ以外の目的ではllvm/llvm-projectリポジトリにブランチを作成しないでください。フォークを使用してください（下記参照）。プルリクエストに関連付けられていないユーザーブランチは**削除されます**。

スタックされたプルリクエストにGraphiteを使用する

Graphiteは、LLVMリポジトリでサポートされているスタック型プルリクエストツールです（もう1つはreviewable.ioです）。

Graphiteは、プライベートフォークではなくllvm/llvm-projectの下にブランチを作成しようとするため、上記のブランチ名の命名に関するガイダンスは非常に重要です。そうでない場合、gt submit（つまり、レビューのためにPRを公開する）は失敗します。

gt config、次にBranch naming settingsとSet a prefix for branch namesを使用してください。最後の/を含めてください。

上記を実行しなかった場合にGraphiteがプレフィックスのないブランチを作成した場合、簡単な解決策として名前を変更し(git -m <古い名前> <新しい名前>)、次にブランチをチェックアウトしてgt trackを実行します。

プルリクエスト

LLVMプロジェクトでは、コードレビューにGitHubプルリクエストを使用しています。このドキュメントでは、プルリクエストの作成、レビュー、承認の一般的なワークフローについて説明します。これはGitHubワークフローの概要であり、完全なドキュメントについてはGitHubのドキュメントを参照してください。

注記

レビュー以外の目的（例：プリコミットCIの結果、便利なWebベースのリバートなど）でプルリクエストを使用する場合は、PRにskip-precommit-approvalラベルを付けます。

GitHubツール

GitHubと対話するには、gitコマンドラインツール、Webブラウザー、GitHub Desktop、またはGitHub CLIなど、いくつかの方法があります。このガイドでは、gitコマンドラインツールとGitHub CLIについて説明します。GitHub CLI（gh）はarcワークフローに最も近く、推奨されます。

プルリクエストの作成

プルリクエストを作成する際には、最初は一般的に自己完結型のコミットを1つだけ含めるようにしてください。これにより、レビュアーは導入された変更を理解し、フィードバックを提供しやすくなります。また、プロジェクトのコミット履歴を明確かつ整理された状態に保つことにも役立ちます。導入したい変更が複数ある場合は、変更ごとに個別のプルリクエストを作成することをお勧めします。

提出する各コミットごとにローカルブランチを作成し、そのブランチをllvm-projectのフォークにプッシュし、フォークからプルリクエストを作成します。GitHubはコミットメッセージの最初の行を72文字に切り詰めてプルリクエストのタイトルとして使用するため、言い換えたり、切り詰めを元に戻したりするために編集する必要がある場合があります。

GitHub CLIを使用したプルリクエストの作成

CLIを使用すると、ローカルにブランチを作成し、次を実行するだけで済みます。

gh pr create

プロンプトが表示されたら、独自のフォークを作成して使用することを選択し、必要な追加情報を追加するための指示に従ってください。

注記

GitHub CLIがユーザーのllvm-projectのフォークを作成すると、gitの「リモート」が変更され、「origin」が自分のフォークを、「upstream」がメインのllvm-projectリポジトリを指すようになります。

プルリクエストの更新

プルリクエストを更新するには、新しいコミットをフォークのブランチにプッシュするだけです。これにより、プルリクエストが自動的に更新されます。

プルリクエストを更新する際は、強制プッシュする代わりに、追加の「修正」コミットをブランチにプッシュする必要があります。これにより、GitHubが以前のレビューコメントのコンテキストを追跡しやすくなります。gitの修正のための組み込みサポートを使用することを検討してください。

これを行う場合は、PRの着陸前にスクワッシュしてマージする必要があり、プルリクエストのタイトルと説明をコミットメッセージとして使用する必要があります。これは、対話型のgit rebaseまたはGitHubの組み込みツールを使用して手動で行うことができます。修正の着陸に関するセクションを参照してください。

ブランチにプッシュする際は、正しいフォークにプッシュしていることを確認してください。リモートは次のように確認します。

git remote -v

そして、自分のフォークを指しているリモートにプッシュしていることを確認してください。

プルリクエストのrebaseと強制プッシュ

一般的に、レビュー中にプルリクエストをrebaseし、プルリクエストのルートであるブランチに強制プッシュすることは避けるべきです。この操作により、古い変更とコメントのコンテキストを見つけて読むのが難しくなります。

テストの修正や依存コードの変更などで、rebaseが必要になる場合があります。

PRがレビューされ、承認された後、PRを着陸させる際にマージの競合が発生しないように、ブランチをrebaseする必要があります。

変更の着陸

PRが承認されたら、Webインターフェースを使用して変更を着陸させることができます。フィードバックに対処するために複数のコミットを作成した場合は、それらのコミットを1つのコミットに統合する必要があります。これを行うには2つの方法があります。

fixupを使用した対話型rebase。これは、最終的なコミットメッセージを制御し、最終的なコミットが期待どおりに見えることを確認できるため、推奨される方法です。ローカルの状態が正しいことを確認したら、ブランチに強制プッシュし、その後マージボタンを押してください。

GitHubのWebインターフェースで「Squash and merge」ボタンを使用します。これを行う場合は、プロンプトが表示されたときにコミットメッセージを確認してください。

その後、「ブランチの削除」オプションを選択して、フォークからブランチを削除できます。

CLIでも、ローカルでブランチに切り替えて次を実行することでマージできます。

gh pr merge --squash --delete-branch

上記から、プルリクエストをマージできないことを示すエラーメッセージが表示された場合は、プルリクエストの作成後にアップストリームが変更され、マージの競合が発生した可能性があります。プルリクエストをマージするには、まずこのマージの競合を解決する必要があります。そのためには

git fetch upstream
git rebase upstream/main

次に、マージの競合を引き起こしているソースファイルを修正し、結果を再構築して再テストしてください。その後

git add <files with resolved merge conflicts>
git rebase --continue

最後に、マージする前にブランチに強制プッシュする必要があります。

git push -f
gh pr merge --squash --delete-branch

この強制プッシュでは、プルリクエストの作成からマージを意図した時点までの期間に応じて、数百または数千のパッチをプッシュするかどうかを確認するメッセージが表示される場合があります。フォーク内のブランチにプッシュしているので、これは問題ありません。GitHubのプルリクエストのUIは、自分のパッチだけをrebaseしていることを理解し、強制プッシュが発生したことを示すメモと共にこの結果を正しく表示します。

変更の着陸後の問題

PRがプリコミットチェックに合格し、レビュアーによって承認されたとしても、着陸後に一部の設定で問題が発生する可能性があります。このような場合は通知され、コミュニティが問題の解決に役立ちます。

このプロセスについては、こちらで詳しく説明されています。

別のPRのローカルでのチェックアウト

ローカルマシンで他の人が作成したPRをレビューして、テストを実行したり、好みのエディターでコードを検査したりする場合があります。これはCLIで簡単に実行できます。

gh pr checkout <PR Number>

これはWebインターフェースと通常のgitコマンドラインツールでも可能ですが、プロセスは少し複雑です。このトピックに関するGitHubのドキュメントを参照してください。

GitHub CLIを使用したプルリクエストの例

GitHub CLIを使用したプルリクエスト作成の例を以下に示します。

# Clone the repo
gh repo clone llvm/llvm-project

# Switch to the repo and create a new branch
cd llvm-project
git switch -c my_change

# Create your changes
$EDITOR file.cpp

# Don't forget clang-format
git clang-format

# and don't forget running your tests
ninja check-llvm

# Commit, use a good commit message
git commit file.cpp

# Create the PR, select to use your own fork when prompted.
# If you don't have a fork, gh will create one for you.
gh pr create

# If you get any review comments, come back to the branch and
# adjust them.
git switch my_change
$EDITOR file.cpp

# Commit your changes
git commit file.cpp -m "Code Review adjustments"

# Format changes
git clang-format HEAD~

# Recommit if any formatting changes
git commit -a --amend

# Push your changes to your fork branch, be mindful of
# your remotes here, if you don't remember what points to your
# fork, use git remote -v to see. Usually origin points to your
# fork and upstream to llvm/llvm-project
git push origin my_change

PRをマージする前に、ローカルでrebaseし、テストチェックを再実行することをお勧めします。

# Add upstream as a remote (if you don't have it already)
git remote add upstream https://github.com/llvm/llvm-project.git

# Make sure you have all the latest changes
git fetch upstream && git rebase -i upstream/main

# Make sure tests pass with latest changes and your change
ninja check

# Push the rebased changes to your fork.
git push origin my_change -f

# Now merge it
gh pr merge --squash --delete-branch

貢献方法に関するより詳細な情報は、次のドキュメントを参照してください。

• LLVMへの貢献

• 最初のタイプミス修正

gitを使用したプルリクエストの例

GitHub CLIを使用してPRを作成する代わりに、コードをフォークのリモートブランチにプッシュし、GitHub Webインターフェースを使用してアップストリームにPRを作成できます。

gitとGitHub Webインターフェースを使用してPRを作成する例を以下に示します。

まず、[リポジトリをフォークする](https://docs.github.com/en/get-started/quickstart/fork-a-repo?tool=webui#forking-a-repository)手順に従ってください。

次に、[フォークされたリポジトリをクローンする](https://docs.github.com/en/get-started/quickstart/fork-a-repo?tool=webui#cloning-your-forked-repository)手順に従ってください。

フォークされたリポジトリをクローンしたら、

# Switch to the forked repo
cd llvm-project

# Create a new branch
git switch -c my_change

# Create your changes
$EDITOR file.cpp

# Don't forget clang-format
git clang-format

# and don't forget running your tests
ninja check-llvm

# Commit, use a good commit message
git commit file.cpp

# Push your changes to your fork branch, be mindful of
# your remotes here, if you don't remember what points to your
# fork, use git remote -v to see. Usually origin points to your
# fork and upstream to llvm/llvm-project
git push origin my_change

前のステップのgit pushコマンドでコンソールに出力されたURLにアクセスしてください。あなたのブランチからllvm::mainへのプルリクエストを作成してください。

# If you get any review comments, come back to the branch and
# adjust them.
git switch my_change
$EDITOR file.cpp

# Commit your changes
git commit file.cpp -m "Code Review adjustments"

# Format changes
git clang-format HEAD~

# Recommit if any formatting changes
git commit -a --amend

# Re-run tests and make sure nothing broke.
ninja check

# Push your changes to your fork branch, be mindful of
# your remotes here, if you don't remember what points to your
# fork, use git remote -v to see. Usually origin points to your
# fork and upstream to llvm/llvm-project
git push origin my_change

PRをマージする前に、ローカルでrebaseし、テストチェックを再実行することをお勧めします。

# Add upstream as a remote (if you don't have it already)
git remote add upstream https://github.com/llvm/llvm-project.git

# Make sure you have all the latest changes
git fetch upstream && git rebase -i upstream/main

# Make sure tests pass with latest changes and your change
ninja check

# Push the rebased changes to your fork.
git push origin my_change -f

PRが承認され、rebaseされ、テストがパスしたら、GitHubウェブインターフェースのPRで「Squash and Merge」をクリックしてください。

貢献方法に関するより詳細な情報は、次のドキュメントを参照してください。

• LLVMへの貢献

• 最初のタイプミス修正

リリース

リリースブランチへの修正のバックポート

リリースブランチに既に追加されている「X.Y.Z リリース」マイルストーンが付いた、いずれかのissueやプルリクエストに以下のコマンドを含むコメントをすることで、リリースブランチへのバックポートリクエストを行うことができます。

/cherry-pick <commit> <commit> <...>

このコマンドは1つ以上のgitコミットハッシュを引数に取り、リリースブランチにコミットをチェリーピックしようとします。コミットがクリーンに適用できない場合、失敗したジョブへのリンクを含むコメントがissue/プルリクエストに追加されます。コミットがクリーンに適用された場合、指定されたコミットを含むプルリクエストが作成されます。

バックポートしたいコミットがクリーンに適用されない場合は、ローカルで競合を解決してから、リリースブランチに対するプルリクエストを作成してください。プルリクエストにリリースマイルストーンを追加することを忘れないでください。