LLVM GitHub 使用者指南¶
簡介¶
LLVM 專案使用 GitHub 進行原始碼、 發布、 Issue 追蹤以及 程式碼審查。
本頁說明 LLVM 專案使用者和開發人員如何使用 GitHub 參與專案。
在您的第一個 PR 之前¶
請確保您已在您的 GitHub 帳戶中設定有效的電子郵件地址，請參閱 電子郵件地址。
分支¶
可以建立以 users/<username>/ 開頭的分支，然而，這旨在支援「堆疊式」合併請求。請勿在 llvm/llvm-project 儲存庫中建立任何其他分支，請使用 fork（見下文）。未與合併請求關聯的使用者分支將會被刪除。
使用 Graphite 進行堆疊式合併請求¶
Graphite 是 LLVM 儲存庫支援的堆疊式合併請求工具（另一個是 reviewable.io）。
Graphite 會希望在 llvm/llvm-project 而不是您的私有 fork 下建立分支，因此上面關於分支命名的指南至關重要，否則 gt submit（即發布您的 PR 以供審查）將會失敗。
使用 gt config 然後 Branch naming settings 和 Set a prefix for branch names。包含最後的 /。
如果您沒有執行上述操作，並且 Graphite 建立了沒有前綴的分支，一個簡單的解除封鎖方法是重新命名 (git -m <old name> <new name>)，然後檢出分支並 gt track。
合併請求¶
LLVM 專案正在使用 GitHub 合併請求進行程式碼審查。本文檔描述了建立合併請求並使其經過審查和接受的典型工作流程。這旨在作為 GitHub 工作流程的概述，如需完整的文件，請參閱 GitHub 的文件。
注意
如果您使用合併請求的目的不是為了審查（例如：precommit CI 結果、方便的基於 Web 的還原等），請新增 skip-precommit-approval 標籤到 PR。
GitHub 工具¶
您可以通過幾種方式與 GitHub 互動：通過 git 命令列工具、Web 瀏覽器、GitHub Desktop 或 GitHub CLI。本指南將涵蓋 git 命令列工具和 GitHub CLI。GitHub CLI (gh) 將最像 arc 工作流程，並且是推薦的。
建立合併請求¶
請記住，在建立合併請求時，它通常最初只應包含一個獨立的提交。這使審查人員更容易理解引入的變更並提供回饋。它還有助於維護專案的清晰且有組織的提交歷史記錄。如果您有多個想要引入的變更，建議為每個變更建立單獨的合併請求。
為您要提交的每個提交建立一個本地分支，然後將該分支推送到您的 llvm-project 的 fork，並 從 fork 建立合併請求。由於 GitHub 使用提交訊息的第一行（截斷為 72 個字元）作為合併請求標題，因此您可能需要編輯以重新措辭或撤銷此截斷。
使用 GitHub CLI 建立合併請求¶
使用 CLI，只需在本地建立分支，然後執行
gh pr create
當出現提示時，選擇建立並使用您自己的 fork，並按照說明新增更多所需的資訊。
注意
當您讓 GitHub CLI 為您的使用者建立 llvm-project 的 fork 時，它將變更 git 「remotes」，以便 「origin」 指向您的 fork，而 「upstream」 指向主要的 llvm-project 儲存庫。
更新合併請求¶
為了更新您的合併請求，您唯一需要做的就是將您的新提交推送到您 fork 中的分支。這將自動更新合併請求。
在更新合併請求時，您應該將額外的「修復」提交推送到您的分支，而不是強制推送。這使 GitHub 更容易追蹤先前審查意見的回覆脈絡。考慮使用 git 中 內建的修復支援。
如果您這樣做，您必須在提交 PR 之前壓縮並合併，並且您必須使用合併請求標題和描述作為提交訊息。您可以使用互動式 git rebase 手動執行此操作，或使用 GitHub 的內建工具。請參閱下面關於提交修復程式碼的部分。
在推送到您的分支時，請確保您推送到正確的 fork。使用以下命令檢查您的 remotes
git remote -v
並確保您推送到指向您的 fork 的 remote。
Rebase 合併請求和強制推送¶
一般來說，在審查期間，您應該避免 Rebase 合併請求並強制推送到作為合併請求根目錄的分支。此操作將使舊變更和意見的回覆脈絡更難找到和閱讀。
有時，可能需要 rebase 以使用測試修復或某些相依程式碼中的修復來更新您的分支。
在您的 PR 經過審查並接受後，您需要 rebase 您的分支，以確保在提交 PR 時不會遇到合併衝突。
注意
本指南假設 PR 分支只有 1 位作者。如果您與其他人在單個分支上協作，請小心您推送變更的方式和時間。--force-with-lease 在這種情況下可能很有用。
核准¶
在合併 PR 之前，您必須獲得所需的核准。請參閱 LGTM - 如何接受修補程式 以獲取更多詳細資訊。
提交您的變更¶
在您的 PR 獲得核准後，請確保
PR 標題和描述描述了最終變更。這些將用作最終壓縮提交的標題和訊息。PR 中提交的標題和訊息將不會被使用。
您已在您的 GitHub 帳戶中設定有效的電子郵件地址，請參閱 電子郵件地址。
注意
GitHub 上的 LLVM 專案單一儲存庫配置為始終使用「壓縮並合併」作為在使用 Web 介面時的合併請求合併選項。使用此選項，GitHub 使用 PR 摘要作為預設提交訊息。
具有寫入權限且可以合併 PR 的使用者有最後一次機會在合併之前編輯提交標題和訊息。但是，此選項不適用於沒有寫入權限的貢獻者。
此時，您可以合併您的變更。如果您沒有儲存庫的寫入權限，則 GitHub Web 介面中的合併按鈕將被停用。如果發生這種情況，請繼續按照此處的步驟操作，但請要求您的審查人員之一代表您點擊合併按鈕。
如果 PR 是單個提交，您只需點擊 GitHub Web 介面中的合併按鈕即可。
如果您的 PR 包含多個提交，您需要將這些提交合併為一個提交。這裡有三種不同的方法可以做到這一點，這裡首先顯示最常用的方法
使用 GitHub Web 介面中的 壓縮並合併 按鈕，如果您這樣做，請記住在出現提示時檢查提交訊息。
之後，您可以選擇 刪除分支 選項以從您的 fork 中刪除分支。
互動式 rebase 與修復。這是推薦的方法，因為您可以控制最終提交訊息並檢查最終提交是否符合您的預期。當您的本地狀態正確時，請記住強制推送到您的分支，然後按下 GitHub Web 介面中的合併按鈕。
使用 GitHub 命令列介面合併。在本地端切換到您的分支並執行
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 --force gh pr merge --squash --delete-branch
此強制推送可能會詢問您是否打算推送數百個或可能數千個修補程式（取決於自您的合併請求最初建立以來與您打算合併它的時間有多長）。由於您要推送到您 fork 中的分支，這是可以接受且預期的。Github 的 PR UI 將理解您正在 rebase 您的修補程式，並正確顯示此結果，並註明發生了強制推送。
合併前持續整合 (CI)¶
多項檢查將應用於合併請求，無論是針對 linting/格式化還是某些建置和測試。這些都不是完美的，您會遇到誤報、基礎架構故障（不穩定或不可用的 worker），或者您會很不幸地將您的變更基於主分支的損壞修訂版本。
沒有任何檢查是嚴格強制性的：這些工具可以幫助我們建置更好的程式碼庫並提高生產力（通過避免在合併後發現的問題和可能的回退）。作為開發人員，您可以自行判斷是否在合併程式碼時繞過任何檢查。
基礎架構可以列印訊息，使其看起來像是強制性的，但這只是 GitHub 基礎架構的產物，而不是專案的政策。
但是，請確保您不要強制合併任何與您的變更直接相關的明顯測試失敗的變更。我們的政策仍然是保持 main 分支處於良好狀態，並且引入稍後要修復的失敗違反了該政策。
合併變更後的問題¶
即使您的 PR 通過了 pre-commit 檢查並獲得了審查人員的核准，它也可能在提交後為某些配置造成問題。如果發生這種情況，您將收到通知，社群已準備好幫助您修復問題。
此過程在 此處 詳細描述。
在本地端檢出另一個 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 --force
# Now merge it
gh pr merge --squash --delete-branch
請參閱以下文件中關於如何貢獻的更深入資訊
使用 git 的合併請求範例¶
除了使用 GitHub CLI 建立 PR 之外，您還可以將您的程式碼推送到您 fork 上的 remote 分支，並使用 GitHub Web 介面建立到上游的 PR。
以下是使用 git 和 GitHub Web 介面建立 PR 的範例
首先按照說明 [fork 儲存庫](https://docs.github.com/en/get-started/quickstart/fork-a-repo?tool=webui#forking-a-repository)。
接下來按照說明 [clone 您的 forked 儲存庫](https://docs.github.com/en/get-started/quickstart/fork-a-repo?tool=webui#cloning-your-forked-repository)。
一旦您 clone 了您的 forked 儲存庫，
# 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 --force
一旦您的 PR 獲得核准、rebase 並且測試通過，請點擊 GitHub Web 介面上 PR 中的 壓縮並合併。
請參閱以下文件中關於如何貢獻的更深入資訊
發布¶
將修復程式碼向後移植到發布分支¶
您可以使用 issue 或合併請求上的特殊註解，為發布分支提出向後移植請求。為此，在您的合併請求被合併後
編輯 issue 或合併請求右側的「里程碑」以顯示「LLVM XY 發布」
在其中新增以下格式的註解
/cherry-pick <commit> <commit> <...>
此命令將一個或多個 git 提交雜湊作為參數，並將嘗試將提交 cherry-pick 到發布分支。如果提交未能乾淨地應用，則會將包含失敗 job 連結的註解新增到 issue/合併請求。如果提交乾淨地應用，則將使用指定的提交建立合併請求。
如果您要向後移植的提交未能乾淨地應用，您可以本地端解決衝突，然後針對發布分支建立合併請求。只需確保將發布里程碑新增到合併請求即可。
取得 CI 基礎架構的管理員存取權限¶
任何負責為 LLVM 專案設定和/或維護 CI 基礎架構的個人都可以請求被授予 LLVM 組織管理員的 CI/CD 角色。可以通過建立 Github issue 並使用 infrastructure 標籤來提出請求。申請人必須包含請求角色的理由。申請由 LLVM 管理員根據具體情況進行審查，並且 LLVM 管理員認為合適時可以隨時撤銷該角色。