LLVM GitHub 用户指南¶

简介¶

本页描述了 LLVM 项目用户和开发者如何使用 GitHub 参与项目。

在你的第一个 PR 之前¶

请确保你在你的 GitHub 账户中设置了有效的电子邮件地址，请参阅电子邮件地址。

分支¶

可以创建以 users/<用户名>/ 开头的分支，但这旨在支持“堆叠式”pull-request。除非使用 fork（见下文），否则不要在 llvm/llvm-project 仓库中创建任何其他分支。与 pull-request 无关的用户分支将被删除。

使用 Graphite 进行堆叠式 Pull Requests¶

Graphite 是 LLVM 仓库支持的堆叠式 pull request 工具（另一个是 reviewable.io）。

Graphite 希望在 llvm/llvm-project 而不是你的私有 fork 下创建分支，因此上面关于分支命名的指导至关重要，否则 gt submit （即，发布你的 PR 以供审查）将失败。

使用 gt config 然后 Branch naming settings 和 Set a prefix for branch names。包括最后的 /。

如果你没有执行上述操作，并且 Graphite 创建了无前缀的分支，那么一个简单的解除阻塞方法是重命名 (git -m <旧名称> <新名称>)，然后检出分支并 gt track。

Pull Requests¶

LLVM 项目正在使用 GitHub Pull Requests 进行代码审查。本文档描述了创建 Pull Request 并使其获得审查和接受的典型工作流程。这旨在作为 GitHub 工作流程的概述，完整的文档请参考 GitHub 的文档。

注意

如果你使用 Pull Request 的目的是审查以外的目的（例如：precommit CI 结果、方便的基于 Web 的回滚等），请添加 skip-precommit-approval 标签到 PR。

GitHub 工具¶

你可以通过几种方式与 GitHub 交互：通过 git 命令行工具、Web 浏览器、GitHub Desktop 或 GitHub CLI。本指南将涵盖 git 命令行工具和 GitHub CLI。 GitHub CLI (gh) 将最像 arc 工作流程，并被推荐使用。

创建 Pull Requests¶

请记住，在创建 pull request 时，它通常最初只应包含一个独立的提交。这使得审查者更容易理解引入的更改并提供反馈。它还有助于维护项目清晰且有组织的提交历史。如果你有多个想要引入的更改，建议为每个更改创建单独的 pull request。

为你想要提交的每个提交创建一个本地分支，然后将该分支推送到你的 llvm-project 的 fork，并从 fork 创建一个 pull request。由于 GitHub 使用提交消息的第一行（截断为 72 个字符）作为 pull request 标题，你可能需要编辑以重新措辞或撤消此截断。

使用 GitHub CLI 创建 Pull Requests¶

使用 CLI，只需在本地创建分支，然后运行

gh pr create

当提示时，选择创建并使用你自己的 fork，并按照说明添加更多所需的信息。

注意

当你让 GitHub CLI 为你的用户创建一个 llvm-project 的 fork 时，它将更改 git “remotes”，以便 “origin” 指向你的 fork，而 “upstream” 指向主 llvm-project 仓库。

更新 Pull Requests¶

为了更新你的 pull request，你唯一需要做的就是将你的新提交推送到你的 fork 中的分支。这将自动更新 pull request。

在更新 pull request 时，你应该将额外的 “fix up” 提交推送到你的分支，而不是强制推送。这使得 GitHub 更容易跟踪先前审查评论的上下文。考虑使用 git 中内置的 fixups 支持。

如果你这样做，你必须在合并 PR 之前进行 squash 和 merge，并且你必须使用 pull request 标题和描述作为提交消息。你可以使用交互式 git rebase 手动执行此操作，也可以使用 GitHub 的内置工具。请参阅下面关于提交你的修复的部分。

当推送到你的分支时，请确保你推送到正确的 fork。使用以下命令检查你的 remotes：

git remote -v

并确保你推送到指向你的 fork 的 remote。

Rebasing Pull Requests 和强制推送¶

通常，在审查期间，你应该避免 rebase Pull Request 并强制推送到作为 Pull Request 根的分支。此操作将使旧更改和评论的上下文更难查找和阅读。

有时，可能需要 rebase 以使用测试修复或某些依赖代码更新你的分支。

在你的 PR 获得审查和接受后，你想要 rebase 你的分支，以确保在提交 PR 时不会遇到合并冲突。

注意

本指南假设 PR 分支只有一个作者。如果你与其他人在一个分支上协作，请小心你推送更改的方式和时间。 --force-with-lease 在这种情况下可能很有用。

批准¶

在合并 PR 之前，你必须获得所需的批准。请参阅 LGTM - 如何接受补丁以获取更多详细信息。

提交你的更改¶

在你的 PR 获得批准后，请确保

PR 标题和描述描述了最终的更改。这些将用作最终 squash 提交的标题和消息。 PR 中提交的标题和消息将不会被使用。

你在你的 GitHub 账户中设置了有效的电子邮件地址，请参阅电子邮件地址。

注意

GitHub 上的 LLVM 项目 monorepo 配置为在使用 Web 界面时始终使用 “Squash and Merge” 作为 pull request 合并选项。使用此选项，GitHub 使用 PR 摘要作为默认提交消息。

具有写入权限且可以合并 PR 的用户在合并之前有最后一次机会编辑提交标题和消息。但是，此选项不适用于没有写入权限的贡献者。

此时，你可以合并你的更改。如果你没有仓库的写入权限，则 GitHub Web 界面中的合并按钮将被禁用。如果是这种情况，请继续执行此处的步骤，但请要求你的审查者之一代表你单击合并按钮。

如果 PR 是单个提交，你只需单击 GitHub Web 界面中的合并按钮即可。

如果你的 PR 包含多个提交，你需要将这些提交合并为一个提交。这里有三种不同的方法可以做到这一点，最常用的方法首先显示

使用 GitHub Web 界面中的 Squash and merge 按钮，如果你这样做，请记住在提示时查看提交消息。

之后，你可以选择 Delete branch 选项从你的 fork 中删除分支。
交互式 rebase 与 fixups。这是推荐的方法，因为你可以控制最终的提交消息并检查最终提交是否符合你的预期。当你的本地状态正确时，请记住强制推送到你的分支，然后按 GitHub Web 界面中的合并按钮。
使用 GitHub 命令行界面合并。切换到你的本地分支并运行
```
gh pr merge --squash --delete-branch
```
如果你观察到上述错误消息通知你你的 pull request 不可合并，那么这很可能是因为上游在你的 pull request 被创建后被修改，导致现在出现合并冲突。你必须首先解决此合并冲突才能合并你的 pull request。为了做到这一点
```
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
```
此强制推送可能会询问你是否打算推送数百个，甚至可能数千个补丁（取决于你的 pull request 最初创建以来与你打算合并它之间的时间有多长）。由于你正在推送到你的 fork 中的分支，这是可以接受的并且是预期的。 Github 的 pull request UI 将理解你只是 rebase 你的补丁，并正确显示此结果，并附带强制推送已发生的注释。

预合并持续集成 (CI)¶

多个检查将应用于 pull-request，无论是用于 linting/格式化还是某些构建和测试。这些都不是完美的，你将遇到误报、基础设施故障（不稳定或不可用的 worker），或者你将是不幸的，并且你的更改基于主分支的损坏版本。

这些检查都不是严格强制性的：这些工具旨在帮助我们构建更好的代码库并提高生产力（通过避免在合并后发现的问题和可能的回滚）。作为开发人员，你有权对合并代码时绕过任何检查做出判断。

基础设施可能会打印出看起来像是强制性的消息，但这只是 GitHub 基础设施的人工产物，而不是项目的策略。

但是，请确保你不要强制合并任何与你的更改直接相关的明显测试失败的更改。我们的政策仍然是保持 main 分支处于良好状态，并且引入稍后要修复的失败违反了该政策。

提交更改后出现问题¶

即使你的 PR 通过了 pre-commit 检查并获得了审查者的批准，它也可能在提交后为某些配置带来问题。如果发生这种情况，你将收到通知，社区已准备好帮助你解决问题。

此过程在此处详细描述。

在本地检出另一个 PR¶

有时你想在本地机器上审查另一个人的 PR，以运行测试或在你喜欢的编辑器中检查代码。使用 CLI 可以轻松完成此操作

gh pr checkout <PR Number>

使用 Web 界面和普通的 git 命令行工具也可以做到这一点，但过程有点复杂。请参阅 GitHub 关于此主题的文档。

使用 GitHub CLI 的 Pull Request 示例¶

这是一个使用 GitHub CLI 创建 Pull Request 的示例

# 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 的 Pull Request 示例¶

除了使用 GitHub CLI 创建 PR 外，你还可以将代码推送到你的 fork 上的远程分支，并使用 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 的 pull request。

# 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 上的 Squash and Merge。

请参阅以下文档，了解有关如何贡献的更深入信息

发布¶

向发布分支反向移植修复¶

你可以在 issue 或 pull request 上使用特殊注释来为发布分支提出反向移植请求。为此，在你的 pull request 合并后

编辑 issue 或 pull request 右侧的 “Milestone” 以显示 “LLVM X.Y Release”
在其中添加以下格式的注释

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

此命令接受一个或多个 git 提交哈希作为参数，并将尝试将提交 cherry-pick 到发布分支。如果提交未能干净地应用，则会将包含指向失败作业的链接的注释添加到 issue/pull request。如果提交干净地应用，则将使用指定的提交创建 pull request。

如果你要反向移植的提交未能干净地应用，你可以本地解决冲突，然后针对发布分支创建一个 pull request。只需确保将发布里程碑添加到 pull request。

获取 CI 基础设施的管理访问权限¶

任何负责为 LLVM 项目设置和/或维护 CI 基础设施的个人都可以请求被授予 LLVM 组织管理员的 CI/CD 角色。可以通过创建一个 Github issue 并使用 infrastructure 标签来提出请求。申请人必须包括请求该角色的理由。申请由 LLVM 管理员根据具体情况进行审查，并且该角色可以随时由 LLVM 管理员酌情撤销。

文档

参与贡献

附加链接

本页