Mcore Split Pr

---
name: mcore-split-pr
description: Split a PR into multiple PRs to reduce the number of required CODEOWNERS reviewer groups.
license: Apache-2.0
when_to_use: User asks to split a PR, reduce reviewer groups, or break up a large PR; 'too many CODEOWNERS', 'split this PR', 'break up PR', 'reduce reviewers needed'.
user_invocable: true
argument: "PR URL or number"
metadata:
  author: Philip Petrakian <ppetrakian@nvidia.com>
---

# Split PR by CODEOWNERS Groups

Split a large pull request into multiple smaller PRs, where each PR touches
the fewest possible CODEOWNERS reviewer groups. The goal is to reduce review
burden: a PR that only touches `megatron/core/` needs only the core reviewers,
while a PR that also touches `examples/`, `tools/`, and `megatron/training/`
pulls in many additional groups.

## Answer-First Constraints

For split-planning questions, lead with these constraints before the full
workflow:

- Minimize CODEOWNERS reviewer groups per PR, but each resulting PR must still
  be independently mergeable and reviewable.
- Tests travel with the production code they validate; do not split tests into a
  separate PR just to reduce reviewer groups.
- If PR B depends on symbols renamed in PR A, call out the dependency and put
  backward-compatible aliases, re-exports, or shims in PR A when needed.
- [GitHub's standard stacked-PR flow](https://docs.github.com/en/pull-requests/how-tos/create-pull-requests/creating-stacked-pull-requests)
  — push each branch to the upstream repo and base each PR on the previous
  branch — does not work here: contributors cannot push branches to
  `NVIDIA/Megatron-LM`, and a PR's base must be an upstream branch. The only
  upstream refs containing a fork PR's commits are the `pull-request/<N>`
  mirrors that copy-pr-bot creates, so stacking goes through them.
- Create every PR with base `main`; the `pull-request/<N>` mirror refs do not
  exist until a vetter comments `/ok to test <head-sha>` (copy-pr-bot). Once
  the mirror exists, stack a dependent PR with
  `gh pr edit <child> --base pull-request/<base PR number>`.
- Never merge a PR while its base is a `pull-request/*` ref: the squash lands
  in the bot's scratch ref, not `main`, and the PR ends up MERGED and
  unreopenable. Retarget to `main` first.
- Wait for user approval before execution.
- Execution creates draft PRs from the right base, applies file-scoped diffs
  with `git diff upstream/main..<source-branch> -- <paths> | git apply`, pushes
  to the user's fork, and never pushes directly to upstream.

## Workflow

### 1. Analyze the PR

1. Fetch the PR details: `gh pr view <number> --repo NVIDIA/Megatron-LM --json title,body,headRefName,author` and `gh pr diff <number> --repo NVIDIA/Megatron-LM --stat`. Also determine the current GitHub user with `gh api user --jq .login`.
2. Parse `.github/CODEOWNERS` to build a mapping from file path patterns to owner groups.
3. For each changed file in the PR, determine which CODEOWNERS groups would be required to review it.
4. Build a summary table grouped by CODEOWNERS group, showing which files pull in which groups.
5. Count the total number of distinct reviewer groups the PR currently requires.

### 2. Propose a split that minimizes reviewer groups per PR

The primary optimization goal: **minimize the number of CODEOWNERS reviewer groups required for each resulting PR**.

Strategy:
1. Cluster files by their CODEOWNERS groups. Files owned by the same set of groups naturally belong together.
2. Identify the largest cluster — this becomes the first (and usually largest) PR.
3. Remaining files form one or more additional PRs, each ideally requiring only one or two reviewer groups.
4. If a split creates a dependency (e.g., PR B uses symbols renamed in PR A), the dependent PR must be merged after the first. Note this explicitly.
5. Each PR must be independently mergeable to main — no broken imports, no missing symbols. Backward-compatible aliases and re-export stubs in the first PR can make this possible.

Present the proposed split as a table:
- PR name/description
- Files included
- CODEOWNERS groups required
- Dependencies on other PRs (if any)

Wait for user approval before proceeding.

### 3. Execute the split (after user approval)

For each new PR:
1. Create a new branch from the appropriate local base (`main`, or a dependency PR's branch).
2. Extract the relevant changes: `git diff upstream/main..<source-branch> -- <file paths> | git apply`.
3. Stage, commit with a clear message, and push to the user's fork.
4. Create the PR as a **draft** with base `main` (per repo contributing guidelines). Retarget dependent PRs to `pull-request/<base PR number>` only after a vetter's `/ok to test` has created that mirror ref.
5. If the original PR needs to be narrowed in scope, confirm with the user before force-pushing.
6. Report all PR URLs when done.

## Important guidelines

- Always create PRs as **drafts** and push to the user's fork, never directly to upstream.
- Backward-compatible changes (aliases, re-exports, deprecation shims) should go in the first PR so subsequent PRs can depend on them.
- Test files should go with the production code they test, not in a separate PR.
- Prefer a single clean commit per split PR over replaying the original commit history.
- If a file is hard to categorize (e.g., it touches two groups), ask the user which PR it should go in.
- If the current GitHub user is not the author of the original PR, each new PR's description must explicitly credit the original author (e.g., "Original changes by @<author> in #<number>").