The pull request is open. This page is what you do when someone comments on the diff.

It is not fork, clone, branch, or the first push. That is the first pull request guide. It is not the title, the body, or Closes #N. That is how to write a pull request description. After it merges, after your first open source contribution is stay or leave. Contribution guidelines and the code of conduct is the bar for how you talk. This page stops at the review thread.

Read the whole review before you push

Do not fix the first comment and push. Open every thread. Read the summary comment if they left one. Note what is blocking and what is a nit.

If two comments conflict, ask once on the newer thread. Do not ship both interpretations.

Reply on the comment, then commit

Every review comment gets one of three replies on that comment, then the commit:

Done. You made the change. Point at the commit if it helps. One line.
Question. You do not understand the request. Ask one concrete question. Do not guess and dump a second design.
Disagree. You think the request is wrong for this issue. One reason, one sentence. Then wait. Do not fight the thread.

Push the follow-up after the replies, not instead of them. A silent new commit with no comment looks like you ignored the review.

One follow-up commit per round

Batch the round into one commit if you can: all the “done” items together. The reviewer re-reads one diff, not six.

Do not force-push over the original commits on a first PR unless they asked. History they already commented on disappearing is a surprise. Extra commits on the same branch are normal.

If CI is red from your follow-up, fix that in the same round before you ping.

Do not expand the PR

Review of issue 12 is not a license to refactor the neighbor module, add a linter, or “while I was here” a second ticket.

Out of scope stays out. If they asked for a larger change, confirm it belongs on this PR or a follow-up. Expanding while addressing review is how a 40-line first PR becomes a 20-file dump they will not merge.

Request changes vs comment vs approve

GitHub review states are not moods. They change what you do:

Approve. They are done. You do not owe more code unless a leftover comment says otherwise. Wait for merge or a bot. Do not keep pushing “improvements.”
Comment. Feedback, not a block. Still reply and fix what you agree with. You can merge only if someone with write access merges — a comment review does not merge itself.
Request changes. Blocking. You must address every thread (done / question / disagree) before you ask them to look again. Use the reply box, then one follow-up commit. Re-request review if you have the button; otherwise a short “addressed, please take another look” on the PR.

Do not resolve conversations you did not address. Let them mark it resolved, or resolve only after “Done” plus the commit.

When the reviewer is wrong: ask, do not fight

Maintainers misread diffs. Tests they named may already exist. A style note may contradict CONTRIBUTING.md.

Reply with the file, the line, or the guide quote. One question. Stop.

Do not stack replies. Do not call it bikeshedding. Do not appeal to a different repo’s style. If they insist and it is still in scope, do it or close your PR. The CoC is argue the patch, not the person — same bar in reverse.

If you are stuck more than a day, say so once. Disappearing after request-changes is how first PRs die.

FAQ

They left 20 nits. Do I fix all of them? Yes if they are in the files you already touched. One commit. If a nit is a repo-wide rename, ask whether it belongs here.

Can I rewrite the PR description in review? Only if they asked, or the behavior actually changed. Review is the threads, not a second essay.

They requested changes, then went silent. Wait a few days. One ping on the PR. Do not open a duplicate PR. Do not @-spam.

Should I mark the PR ready again? If it was still a draft, mark ready when the blocking threads are addressed. If it was already ready, you just push and reply.

What if I disagree on every comment? Then this may be the wrong issue or the wrong project. Say that once, close if you will not change the diff, and pick another ticket. Do not burn the thread.

The job is: read the round, reply on each comment, one follow-up commit, stay on the issue. That is the whole page.