文档类PR批量合并
概述
许多小的文档Pull Request分开合并繁琐，将它们合并为一个审阅起来更简单。本流程将多个已审核的文档专用Pull Request中的文件复制到一个新的草稿Pull Request中，每个源PR对应一个独立提交。文件内容原样复制，不做任何编辑。源PR保持原样不动。审阅者随后合并这一个批量PR，而源PR通过它们自身的状态关闭，不通过本流程中的任何操作。
何时使用
- 多个开放的文档Pull Request已通过审核，并且每个PR只涉及文档路径。
- 审阅者要求用一个Pull Request将它们合并在一起。
不要将此技能用于代码、配置或任何未通过审核的源Pull Request。
特性
- 使用一个临时工作树，不触动当前工作目录。
- 实时快照每个源PR的状态、基础分支、HEAD提交和文件列表，并与拉取的HEAD提交进行核对。
- 跳过规则：对于已关闭、涉及文档文件夹之外的路径、与主分支冲突或与其他开放PR冲突的PR进行跳过。
- 每个合并的源PR对应一个独立提交，并带有断言，遇到错误源时终止运行。
- 推送前对变更路径进行门控检查，验证变更文件数量是否等于所有源PR的文件路径数量之和。
- 生成验证块，比较批量分支中每个文件的blob与源HEAD的blob是否一致。
优势
- 错误的源PR会停止运行，而不是部分合并。
- 每个合并的文件内容都被证明与其源文件完全相同。
- 跳过的PR会列出原因，不会静默丢失任何内容。
- 批量PR以草稿形式创建，审阅者做出最终决定。
流程
-
在临时工作树中操作。 拉取主分支和源PR的HEAD，然后在临时目录中基于主分支创建一个新分支：
git fetch origin main '+refs/pull/*/head:refs/remotes/origin/pr/*' git worktree add -b <batch-branch> <scratch-dir>/wt origin/main如果HTTPS拉取或推送因认证失败，请为该命令设置凭证助手指向代码托管的CLI，例如
-c credential.helper= -c 'credential.helper=!gh auth git-credential'。不要更改存储的配置，也不要打印令牌。 -
一次性快照当前状态。 对于每个源PR，读取其状态、草稿标志、基础分支、HEAD提交和文件列表。同时列出所有开放PR用于冲突检查。断言每个源PR的HEAD提交与拉取的
refs/remotes/origin/pr/<n>提交一致。 -
按编号顺序决定跳过或合并。 如果满足以下任一条件，则跳过该PR并记录原因：
- PR不是开放状态。
- 其任何路径在文档文件夹之外。
- 其任何路径已存在于主分支上。对于已存在于主分支的路径，比较其blob。内容相同表示已提前合并；内容不同表示需要变基。
- 有其他开放PR更改了其任何路径。
-
以独立提交方式合并每个PR。 对于每个要合并的PR，从其HEAD提交中检出文件，并用包含PR编号的消息提交。在循环中运行，断言PR为开放状态、HEAD匹配、路径均在文档文件夹下、且没有任何文件存在于主分支上。失败的断言会停止运行。
git checkout <head-commit> -- <paths> git commit -m "docs: land #<n>" -
推送前对变更进行门控检查。 文档文件夹之外的变更文件数量必须为零。变更文件总数必须等于所有源PR路径数量之和。
-
构建验证块。 对于每个PR及其每个路径，比较批量分支
HEAD上的blob与源HEAD上的blob。每个PR打印一行，显示其HEAD、路径数、blob数和MATCH，以及总计行。将验证块原样粘贴到批量PR的描述中。 -
以草稿形式创建批量PR。 推送分支，然后针对主分支创建草稿PR。标题声明实际合并的PR数量，而非考虑的数量：
gh pr create --draft --base main --title "docs: land <k> reviewed docs PRs" --body-file <body-file> -
编写描述。 包含一条注释（说明由于仅文档变更，构建已跳过）、合并的PR列表及其文件数量和HEAD、跳过的PR及其原因、给审阅者的任何标志，以及验证块。重新读取新PR的状态，确认它是以主分支为基础创建的草稿。
陷阱
- 忽略草稿规则。 运行指令可能要求创建“待审阅”而非“草稿”的PR。除非运行规则另有说明，请以草稿形式创建，并在描述中说明。
- 源PR基于其他分支。 其文件符合所有路径规则，但将它们合并到主分支会改变该PR的语义。仅在规则允许时包含它，并用精确的提交标记它，以便丢弃。
- 没有合并基础。 此类PR可能无法查找合并基础，与基础分支的diff会出错。请使用实时文件列表作为路径来源。仅在存在合并基础时，才使用与基础分支的diff进行交叉检查。
- 部分合并。 修改了主分支已有文件的PR，即使其其他文件是新的，也可能跳过。不要仅合并其一部分。
- 输出中充斥着缺失路径错误。 检查路径是否存在于主分支时，对于每个缺失路径会打印一条错误。在这些检查中将标准错误重定向到
/dev/null。 - 最终报告中过度罗列。 报告中只列出跳过的PR及其原因、标志和验证总计。不要列出每个文件。
- 缺少图表或索引。 如果仓库的代码智能索引不可用，请在报告中说明，并且不要跳过路径规则。
验证
- 批量PR是以主分支为基础的草稿。
- 所有合并的文件blob与其源HEAD匹配，如验证块所示。
- 没有变更文件位于文档文件夹之外。
- 每个跳过的PR在描述中都有原因。
- 源PR保持不变。本流程不会合并、批准、关闭或评论它们。