mcore-split-pr

按 CODEOWNERS 分组拆分 PR

将大型拉取请求拆分为多个较小的 PR，使每个 PR 涉及的 CODEOWNERS 审核组尽可能少。目标是减轻审核负担：只涉及 megatron/core/ 的 PR 只需要核心审核人员，而同时涉及 examples/、tools/ 和 megatron/training/ 的 PR 则会牵涉许多其他组。

优先说明的约束

对于拆分规划问题，请先说明以下约束，再介绍完整工作流：

• 尽量减少每个 PR 涉及的 CODEOWNERS 审核组，但每个拆分后的 PR 仍必须能够独立合并和审核。
• 测试应与其验证的生产代码放在一起；不要仅仅为了减少审核组而把测试拆到单独的 PR 中。
• 如果 PR B 依赖于 PR A 中重命名的符号，请指出这一依赖，并在需要时于 PR A 中添加向后兼容的别名、重新导出或垫片。
• 执行前须等待用户批准。
• 执行时会从正确的基准创建草稿 PR，使用 git diff upstream/main..<source-branch> -- <paths> | git apply 应用限定文件范围的差异，将更改推送到用户的 fork，且绝不直接推送到上游仓库。

工作流

1. 分析 PR

1. 获取 PR 详情：gh pr view <number> --repo NVIDIA/Megatron-LM --json title,body,headRefName,author 和 gh pr diff <number> --repo NVIDIA/Megatron-LM --stat。同时使用 gh api user --jq .login 确定当前 GitHub 用户。
2. 解析 .github/CODEOWNERS，建立文件路径模式到所有者组的映射。
3. 对 PR 中每个更改的文件，确定审核它需要哪些 CODEOWNERS 组。
4. 按 CODEOWNERS 组汇总并生成摘要表，显示哪些文件涉及哪些组。
5. 统计 PR 当前需要的不同审核组总数。

2. 提出尽量减少每个 PR 审核组数量的拆分方案

首要优化目标：尽量减少每个拆分后的 PR 所需的 CODEOWNERS 审核组数量。

策略：

1. 按 CODEOWNERS 组对文件进行聚类。由同一组所有者负责的文件自然适合放在一起。
2. 找出最大的聚类——它将成为第一个（通常也是最大的）PR。
3. 其余文件组成一个或多个额外的 PR，每个 PR 最好只需要一两个审核组。
4. 如果拆分产生依赖（例如，PR B 使用了 PR A 中重命名的符号），依赖 PR 必须在第一个 PR 合并后再合并。请明确说明这一点。
5. 每个 PR 都必须能够独立合并到 main——不能有损坏的导入或缺失的符号。第一个 PR 中的向后兼容别名和重新导出占位代码可以实现这一点。

以表格形式展示拆分方案：

• PR 名称/描述
• 包含的文件
• 所需的 CODEOWNERS 组
• 对其他 PR 的依赖（如有）

继续操作前须等待用户批准。

3. 执行拆分（用户批准后）

对于每个新 PR：

1. 从适当的基准（main 或某个依赖 PR 的分支）创建新分支。
2. 提取相关更改：git diff upstream/main..<source-branch> -- <file paths> | git apply。
3. 暂存、使用清晰的提交信息提交，并推送到用户的 fork。
4. 根据仓库贡献指南，将 PR 创建为草稿。
5. 如果需要缩小原 PR 的范围，请在强制推送前向用户确认。
6. 完成后报告所有 PR URL。

重要准则

• 始终将 PR 创建为草稿，并推送到用户的 fork，绝不要直接推送到上游仓库。
• 向后兼容的更改（别名、重新导出、弃用兼容层）应放在第一个 PR 中，以便后续 PR 可以依赖这些更改。
• 测试文件应与其测试的生产代码放在一起，而不是单独放在一个 PR 中。
• 拆分后的 PR 优先使用单个干净的提交，而不是重放原始提交历史。
• 如果某个文件难以归类（例如涉及两个分组），请询问用户应将其放入哪个 PR。
• 如果当前 GitHub 用户不是原始 PR 的作者，则每个新 PR 的描述都必须明确注明原作者（例如：“原始更改由 @ 在 # 中提交”）。