diff --git a/AGENTS.md b/AGENTS.md index 8972d4e242..9b611dd9bd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -139,6 +139,10 @@ UPDATE_SNAPSHOTS=1 just snapshot-test # record/accept snapshots Snapshot mismatches fail the run with a unified diff and write `.md.new`; recorded `.md` snapshots are reviewed like code and committed with the fixture. Steps are argv arrays (no shell); use `vpt` subcommands instead of coreutils so cases stay platform-identical. Cases declare `vp = "local" | "global" | ["local", "global"]`; local-flavor cases require a fresh `packages/cli/dist`. +### Submitting changes + +Prioritize stacked pull requests: split multi-part work into a stack of small PRs so reviewers can approve and merge each layer on its own. Create stacks with the `gh-stack` CLI extension or on github.com. Stacks require all branches to be in this repository (GitHub does not support cross-fork stacks), so from a fork submit standalone PRs instead. See the "Submitting Pull Requests" section in `CONTRIBUTING.md`. + ## Code Conventions ### Rust diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1ce2a40d67..e8073f9c98 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -155,6 +155,18 @@ UPDATE_SNAPSHOTS=1 just snapshot-test create The full case/step/interaction reference (including the `vpt` helper tool and milestone conventions for interactive tests) lives in `crates/vite_cli_snapshots/tests/cli_snapshots/README.md`; the design rationale is in `rfcs/interactive-snapshot-tests.md`. +## Submitting Pull Requests + +Prioritize stacked pull requests when your work splits into reviewable layers, for example a refactor PR with the feature PR that depends on it stacked on top. Reviewers handle a stack of small PRs faster than one large PR, and each layer merges on its own. + +GitHub has built-in stacked pull requests ([public preview](https://github.blog/changelog/2026-07-30-stacked-pull-requests-are-now-in-public-preview/), rolling out to all repositories). Create stacks on github.com, or from the terminal: + +```bash +gh extension install github/gh-stack +``` + +Stacked pull requests require all branches to be in this repository; GitHub does not support cross-fork stacks ([reference](https://docs.github.com/en/pull-requests/reference/stacked-pull-requests)). If you contribute from a fork, split large work into a sequence of standalone PRs instead. + ## Verified Commits All commits in PR branches should be GitHub-verified so reviewers can confirm commit authenticity. @@ -162,7 +174,6 @@ All commits in PR branches should be GitHub-verified so reviewers can confirm co Set up local commit signing and GitHub verification first: - Follow GitHub's guide for GPG commit signature verification: https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification#gpg-commit-signature-verification -- If you use Graphite, add the Graphite GPG key to your GitHub account from the Graphite UI as well, otherwise commits updated by Graphite won't show as verified. After setup, re-sign any existing commits in your branch so the full branch is verified: