Pull Requests

Pull requests

Pushing is the middle of the task. The PR is done when the checks pass and a review round produces nothing left to act on. Until then the work is yours.

Several bots review this repository, and they re-review on every push. A push therefore always buys a new round, and the round arrives minutes later, after the turn that pushed would otherwise have ended. Stay for it.

Opening

Open it as a draft (gh pr create --draft). Fill in .github/pull_request_template.md and pass it as the body; gh pr create does not apply the template on its own. Keep every section, mark the checklist honestly, and drop only the lines the template says to drop.

When the change comes from an issue, link it from the Summary with a closing keyword (Closes pnpm/pnpm#123) and then comment on the issue itself. The cross-reference GitHub adds to the issue timeline is silent and says nothing about what was done, so the people waiting on the issue learn nothing from it. The comment carries what they need: that a PR is open, the approach it takes, and whether it covers the whole issue or one part of it. Say so plainly when it is partial. Do not close the issue by hand; the closing keyword does that when the PR merges.

Draft until the change is worth reading

CI runs on a draft here; the reviewers do not. That asymmetry is the whole point of opening as one. A failing lint job, a test you forgot to update, a bug your own review pass catches — in draft each of those costs a push and nothing else, while on a ready PR each one burns a review round and leaves a thread behind.

So stay in draft until the checks are green and your own pass over the diff is clean, then gh pr ready <pr>. The first round of review then reads a finished change instead of a half-fixed one, and its findings are about the design rather than the leftovers.

Do not leave a draft behind when you stop. A draft with no note on it reads as abandoned: either mark it ready or say in a comment what is left to do.

After every push

This is the loop for a PR that is ready for review. Steps 1 and 4 apply while it is still a draft too; the review steps start when you mark it ready.

1. Wait for the checks. gh pr checks <pr> --watch blocks for longer than a foreground command is usually allowed to run, so run it in the background or poll it. Started in the same breath as the push it can return before the runs exist; give the push a moment first. Watch to the end rather than stopping at the first failure: the push that fixes it cancels whatever was still running, so a second failure you never waited for costs another full cycle.
2. Read the whole round. Inline threads are not the whole review. A reviewer may post only its worst findings inline and leave the rest in a summary comment, so listing the PR's review comments misses findings. Read the issue comments and the review bodies too, whoever wrote them.
3. Verify every finding yourself before acting on it. Treat every reviewer the same way, bot or human: a meaningful share of findings are wrong, and a fix applied to a finding you did not check is a new bug with a reviewer's blessing on it. A priority or severity badge is the reviewer's guess, not a verdict. Act on what holds. Reply on every thread either way, naming the commit that fixed it or the reason you are not acting, and then resolve it: the thread is the record a reviewer checks each fix against. Reply once that commit is on the remote branch, never before — a hash read off a local commit that a rebase or an amend then rewrites names something nobody can look up. Resolving needs GraphQL (resolveReviewThread); the REST comment API cannot do it.
4. Bring the title and description with the code. Reread them after any push that changes what the PR does, and edit them when they no longer describe it (gh pr edit --title, --body). This is not housekeeping: the title becomes the squash commit's subject and the template's Squash Commit Body section becomes its message, so whatever is stale at merge time is what lands in the history for good.
5. Go back to 1 after the push that carries the fixes.

A round is finished only when every reviewer's summary comment names your head commit; each one says which commit it reviewed. Green checks and an empty comment list prove nothing on their own, because a round that has not started yet looks exactly like one that found nothing. Stop when every reviewer has reported on the head commit, none of them found anything left to act on, and the checks are green.

Report at the end which findings were real, which were not, and anything you declined that a human should settle.