LLVM GitHub 使用者指南¶
簡介¶
LLVM 專案使用 GitHub 進行 原始碼、版本發佈、問題追蹤 和 程式碼審查。
本頁說明 LLVM 專案的使用者和開發者如何使用 GitHub 參與專案。
分支¶
可以建立以 users/<username>/ 開頭的分支，但這是為了支援「堆疊式」拉取請求。請勿在 llvm/llvm-project 儲存庫中建立任何其他分支，請使用分支（見下文）。與拉取請求無關的使用者分支**將被刪除**。
使用 Graphite 進行堆疊式拉取請求¶
Graphite 是一個由 LLVM 儲存庫支援的堆疊式拉取請求工具（另一個是 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 的便捷還原等），請將 skip-precommit-approval 標籤添加到 PR。
GitHub 工具¶
您可以透過幾種方式與 GitHub 互動：透過 git 命令列工具、網頁瀏覽器、GitHub Desktop 或 GitHub CLI。本指南將涵蓋 git 命令列工具和 GitHub CLI。GitHub CLI (gh) 將與 arc 工作流程最為相似，建議使用。
建立拉取請求¶
請記住，建立拉取請求時，最初通常應該只包含一個獨立的提交。這讓審閱者更容易理解引入的變更並提供回饋。它還有助於維護專案清晰且有條理的提交歷史記錄。如果您要引入多個變更，建議為每個變更建立單獨的拉取請求。
為您要提交的每個提交建立一個本地分支，然後將該分支推送到您的 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
並確保您推送到指向您分支的遠端。
變更拉取請求的基準和強制推送¶
一般而言，您應該避免在審閱期間變更拉取請求的基準並強制推送到作為拉取請求根目錄的分支。此操作將使舊變更和註解的上下文更難找到和閱讀。
有時，可能需要變更基準以使用測試修復或某些相依程式碼中的修復來更新您的分支。
在您的 PR 經過審閱和接受後，您需要變更基準您的分支，以確保您在合併 PR 時不會遇到合併衝突。
合併您的變更¶
當您的 PR 被接受後，您可以使用網路介面來合併您的變更。如果您在此時建立了多個提交以解決回饋，則需要將這些提交合併為一個提交。您可以透過兩種不同的方式來完成此操作
使用 fixup 進行互動式變基。這是推薦的方法，因為您可以控制最終的提交訊息，並檢查最終的提交是否符合您的預期。當您的本地狀態正確時，請記住要強制推送至您的分支，然後按下合併按鈕。
使用 GitHub 網頁介面中的 壓縮並合併 按鈕，如果您這樣做，請記住系統提示時要檢查提交訊息。
之後，您可以選擇 刪除分支 選項，從您的分支中刪除分支。
您也可以透過 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 的拉取請求使用者介面會瞭解您只是在變基您的修補程式，並使用強制推送已發生的說明正確顯示此結果。
提交變更後的出現問題¶
即使您的 PR 通過了預先提交檢查並獲得審閱者的批准，它也可能在某些配置中在提交後導致問題。如果發生這種情況，您會收到通知，社群隨時準備幫助您解決問題。
此過程在這裡有詳細說明。
在本地簽出另一個 PR¶
有時，您想在本地機器上審閱其他人的 PR，以執行測試或在您偏好的編輯器中檢查程式碼。使用 CLI 可以輕鬆完成
gh pr checkout <PR Number>
這也可以透過網頁介面和一般的 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 之前，建議您在本地重新設定基準並重新執行測試檢查
# 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
請參閱以下文件中關於如何貢獻的更多詳細資訊
使用 git 的拉取請求範例¶
除了使用 GitHub CLI 建立 PR 之外，您還可以將程式碼推送至分支上的遠端分支，並使用 GitHub 網頁介面建立到上游的 PR。
以下是如何使用 git 和 GitHub 網頁介面建立 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 之前，建議您在本地重新設定基準並重新執行測試檢查
# 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
當您的拉取請求獲得批准、變基並通過測試後，請在 GitHub 網頁介面中點擊您拉取請求上的「壓縮並合併」。
請參閱以下文件中關於如何貢獻的更多詳細資訊
版本發佈¶
將修正回溯至發佈分支¶
您可以在議題或拉取請求上使用特殊的註解來對發佈分支提出回溯請求。這可以透過在任何已加入「X.Y.Z 發佈」里程碑的議題或拉取請求上留下包含以下指令的註解來完成。
/cherry-pick <commit> <commit> <...>
此指令會將一個或多個 git 提交雜湊作為參數，並嘗試將提交挑選至發佈分支。如果提交無法順利套用，則會在議題/拉取請求中新增一個包含失敗作業連結的註解。如果提交順利套用，則會使用指定的提交建立一個拉取請求。
如果您想要回溯的提交無法順利套用，您可以選擇在本地端解決衝突，然後針對發佈分支建立一個拉取請求。請務必將發佈里程碑新增至拉取請求中。