From dd1513489ecba88ea82df794c4efb3e22ed5e3dd Mon Sep 17 00:00:00 2001 From: Kelvin Lee Date: Thu, 10 Sep 2026 13:16:53 -0700 Subject: [PATCH 1/2] docs: document PR stacking workflow and branch naming Add a stacking bullet to AGENTS.md using the `//` branch scheme, and a "Stacking Pull Requests" section to CONTRIBUTING.md covering the same-repository requirement and the two supported workflows: the `gh stack` commands in GitHub CLI and the GitHub website. Signed-off-by: Kelvin Lee --- AGENTS.md | 6 ++++++ CONTRIBUTING.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index e88f145e..08e6f5ef 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,6 +24,12 @@ dynamics, hooks/reporting, and training/finetuning workflows. for DCO details, hook setup, and CI stages. - The PR template expects a short description, testing notes, changelog updates, docstring/docs updates where applicable, and the relevant type-of-change box. +- When stacking PRs, use either the `gh stack` commands in GitHub CLI + (`gh stack init`, `gh stack add`, `gh stack submit`) or the GitHub website + (each pull request targets the layer below, linked with **Create stack**). + Name branches `//` (e.g. + `octocat/batched-dynamics/01`); all branches in a stack live on this + repository. See `CONTRIBUTING.md` for the procedure. - Keep work tightly scoped; read `docs/userguide/about/` before broad changes. ## CUDA And Environment Setup diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 88113885..a0e9a155 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -138,3 +138,47 @@ The pipeline has following stages: Aim for more than 80% code coverage. To test coverage locally, run the `get_coverage.sh` script from the `test` folder and check the coverage of the module that you added/edited. + +## Stacking Pull Requests + +This repository supports PR stacking: splitting a large change into a series of +small pull requests that build on each other, so every layer can be reviewed on +its own. + +GitHub does not currently support dependent pull requests across forks, so all +branches of a stack must be created on this repository rather than on a fork. +This means stacking requires write access to the repository. + +Name the branches of a stack `//`, +for example `octocat/batched-dynamics/01` and `octocat/batched-dynamics/02`. +The shared topic shows which branches belong to one stack, and the layer is +the position in it. + +There are two ways to build a stack, both documented by GitHub: + +- With the `gh stack` commands in GitHub CLI (see the + [quickstart][gh-stacked-quickstart]): + + ```bash + gh stack init # first branch, e.g. octocat/batched-dynamics/01 + gh stack add octocat/batched-dynamics/02 + gh stack submit # push branches and open the linked pull requests + gh stack sync --prune # after the bottom pull request merges and is deleted + ``` + +- On the GitHub website, without the CLI: open each pull request with its + base branch set to the layer below, then link the pull requests with the + **Create stack** option; after merges, the **Rebase stack** button in the + merge box rebases the remaining layers server-side (see + [creating stacked pull requests][gh-stacked-web]). + +Either way, the first pull request targets `main` and each later one targets +the branch below it, so reviewers see only that layer's diff. When the bottom +pull request merges and its branch is deleted, GitHub retargets the next layer +onto the merged pull request's base branch. + +Commits in a stack follow the same rules as any other contribution: sign off +with `git commit -s` and keep pre-commit green. + +[gh-stacked-quickstart]: https://docs.github.com/en/pull-requests/get-started/stacked-prs-quickstart +[gh-stacked-web]: https://docs.github.com/en/pull-requests/how-tos/create-pull-requests/creating-stacked-pull-requests From f41d8373180d1ad3286c67ceb1c843ac44a04188 Mon Sep 17 00:00:00 2001 From: Kelvin Lee Date: Thu, 10 Sep 2026 13:37:06 -0700 Subject: [PATCH 2/2] docs: note gh-stack extension prerequisite for stacked PRs The `gh stack` commands ship as the `github/gh-stack` GitHub CLI extension rather than built-in commands; note the conditional install step in both AGENTS.md and CONTRIBUTING.md. Addresses Greptile review feedback. Signed-off-by: Kelvin Lee --- AGENTS.md | 5 +++-- CONTRIBUTING.md | 5 +++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 08e6f5ef..a2770785 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,8 +25,9 @@ dynamics, hooks/reporting, and training/finetuning workflows. - The PR template expects a short description, testing notes, changelog updates, docstring/docs updates where applicable, and the relevant type-of-change box. - When stacking PRs, use either the `gh stack` commands in GitHub CLI - (`gh stack init`, `gh stack add`, `gh stack submit`) or the GitHub website - (each pull request targets the layer below, linked with **Create stack**). + (`gh extension install github/gh-stack` if unavailable) or the GitHub + website (each pull request targets the layer below, linked with **Create + stack**). Name branches `//` (e.g. `octocat/batched-dynamics/01`); all branches in a stack live on this repository. See `CONTRIBUTING.md` for the procedure. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a0e9a155..f863087f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -156,10 +156,11 @@ the position in it. There are two ways to build a stack, both documented by GitHub: -- With the `gh stack` commands in GitHub CLI (see the - [quickstart][gh-stacked-quickstart]): +- With the `gh stack` commands in GitHub CLI, provided by the + `github/gh-stack` extension (see the [quickstart][gh-stacked-quickstart]): ```bash + gh extension install github/gh-stack # if `gh stack` is not available gh stack init # first branch, e.g. octocat/batched-dynamics/01 gh stack add octocat/batched-dynamics/02 gh stack submit # push branches and open the linked pull requests