LLVM GitHub 用户指南¶
简介¶
LLVM 项目使用 GitHub 进行 源代码管理、版本发布、问题追踪 和 代码审查。
此页面描述了 LLVM 项目用户和开发者如何使用 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 的文档。
注意
如果您出于除审查之外的目的使用拉取请求（例如：预提交 CI 结果、方便的基于 Web 的回滚等），请在 PR 中添加 skip-precommit-approval 标签。
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 的“远程”，以便“origin”指向您的 fork，“upstream”指向主 llvm-project 代码库。
更新拉取请求¶
为了更新您的拉取请求，您只需要将新的提交推送到您 fork 中的分支即可。这将自动更新拉取请求。
更新拉取请求时，您应将额外的“修复”提交推送到您的分支，而不是强制推送。这使 GitHub 更容易跟踪先前审查评论的上下文。考虑使用 git 中 内置的修复支持。
如果您这样做，则必须在合并 PR 之前进行压缩和合并，并且必须使用拉取请求标题和描述作为提交消息。您可以使用交互式 git rebase 或 GitHub 的内置工具手动执行此操作。请参阅下面关于合并您的修复的部分。
推送到您的分支时，请确保推送到正确的 fork。使用以下命令检查您的远程：
git remote -v
并确保您推送到指向您 fork 的远程。
拉取请求的变基和强制推送¶
通常，您应该避免在审查期间变基拉取请求并强制推送到作为拉取请求根的分支。此操作将使旧更改和评论的上下文难以查找和阅读。
有时，可能需要进行变基以更新您的分支以修复测试或某些依赖代码中的错误。
在您的 PR 被审查并接受后，您需要变基您的分支以确保在合并 PR 时不会遇到合并冲突。
合并您的更改¶
当您的 PR 被接受后，您可以使用 Web 界面合并您的更改。如果您已创建多个提交以解决反馈，则此时需要将这些提交合并为一个提交。有两种不同的方法可以做到这一点
交互式变基 和修复。这是推荐的方法，因为您可以控制最终提交消息并检查最终提交是否符合您的预期。当您的本地状态正确后，请记住强制推送到您的分支，然后按下合并按钮。
使用 GitHub Web 界面中的 压缩并合并 按钮，如果您这样做，请记住在出现提示时查看提交消息。
之后，您可以选择 删除分支 选项以从您的 fork 中删除分支。
您也可以通过 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
此强制推送可能会询问您是否打算推送数百个或可能数千个补丁（具体取决于自您最初创建拉取请求以来与您打算合并它时之间的时间长短）。由于您正在推送到您 fork 中的分支，因此这可以接受，并且是预期的。GitHub 的拉取请求 UI 将了解您只是在变基您的补丁，并通过一条说明强制推送已发生的注释正确显示此结果。
合并更改后的问题¶
即使您的 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 之前，建议您在本地进行变基并重新运行测试检查
# 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 的拉取请求示例¶
您可以将代码推送到 fork 上的远程分支，而不是使用 GitHub CLI 创建 PR，并使用 GitHub Web 界面向上游创建 PR。
以下是如何使用 git 和 GitHub Web 界面创建 PR 的示例
首先按照说明 [fork 代码库](https://githubdocs.cn/en/get-started/quickstart/fork-a-repo?tool=webui#forking-a-repository）。
接下来，按照说明 [克隆您 fork 的代码库](https://githubdocs.cn/en/get-started/quickstart/fork-a-repo?tool=webui#cloning-your-forked-repository）。
克隆您 fork 的代码库后，
# 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
您的 PR 获批、重新基准化且测试通过后，请在 GitHub 网页界面上的 PR 中点击 Squash and Merge。
在以下文档中查看有关如何贡献的更深入信息
发布版本¶
将修复程序回移植到发布分支¶
您可以在问题或拉取请求中使用特殊注释来发出回移植到发布分支的请求。这可以通过在已添加到“X.Y.Z 发布版本”里程碑的任何问题或拉取请求上添加包含以下命令的注释来完成。
/cherry-pick <commit> <commit> <...>
此命令接受一个或多个 Git 提交哈希作为参数，并尝试将提交挑选到发布分支。如果提交无法干净地应用，则会在问题/拉取请求中添加一条包含失败作业链接的注释。如果提交能够干净地应用，则会创建一个包含指定提交的拉取请求。
如果您要回移植的提交无法干净地应用，您可以本地解决冲突，然后针对发布分支创建拉取请求。只需确保将发布版本里程碑添加到拉取请求中即可。