Pull requests and code review — Git & the Command Line

Open a pull request from a branch, review changes line by line, and respond to review comments with new commits.

Why it matters

On most teams, nobody pushes straight to main. Changes go on a branch, and a pull request (PR) asks for that branch to be merged. Teammates review the diff, comment, request changes and approve; automated checks run tests. This catches bugs, spreads knowledge across the team and leaves a written record of why each change was made. Knowing how to open a clear PR and handle feedback gracefully is a core professional skill.

The pull request workflow

Update main: git switch main && git pull.
Branch: git switch -c add-site-checklist.
Commit focused changes on the branch.
Push the branch: git push -u origin add-site-checklist.
Open the PR on GitHub: a yellow banner offers Compare & pull request, or use the Pull requests tab > New pull request, with base main and compare add-site-checklist.
Review: reviewers read the Files changed tab and comment.
Respond: push more commits to the same branch; the PR updates automatically.
Merge when approved and checks pass, then delete the branch.

Writing a good PR

Title: a short summary, like a commit message: "Add pre-visit safety checklist".

Description: answer what, why and how to check:

## What
Adds checklist.md with the items to confirm before a site visit.

## Why
We forgot the spare batteries twice last month.

## How to check
Open checklist.md and compare it with the equipment list in notes.md.

Keep PRs small. A 50-line PR gets a careful review; a 2,000-line PR gets a rubber stamp. If you are not finished, open it as a draft pull request to share early work.

Reviewing code

On the Files changed tab:

Hover a line and click the + to comment on it. Use Start a review to batch several comments.
Use the suggestion button (the file icon with +/- in the comment box) to propose exact replacement text the author can accept with one click.
Finish with Review changes: Comment, Approve or Request changes. (You cannot approve your own PR, but you can comment on it.)

Good review comments are specific, kind and about the code, not the person:

Unhelpful	Helpful
"This is wrong."	"This adds up the hours, but the header says minutes. Should it be `* 60`?"
"Bad name."	"Could we call this `site_count` instead of `x`? It took me a while to see what it holds."
(silence on good work)	"Nice, the checklist order matches the visit plan."

Mark small preferences as optional, for example "nit: extra blank line".

Responding to a review

Make the change on the same branch, commit with a clear message ("Use minutes in total, per review"), and push. The new commit appears in the PR.
Reply to each comment: "Done in 3a1f9e2", or explain why you chose differently. Disagreeing politely with reasons is fine.
Resolve conversation once a thread is handled, so reviewers can see what is left.
Re-request review with the circular arrow icon next to the reviewer's name.

Do not take review personally. Comments are about making the work better, and senior engineers get them too.

Merging and cleaning up

GitHub offers three merge buttons:

Create a merge commit: keeps every commit and adds a merge commit.
Squash and merge: combines all the PR's commits into one on main. Common on teams that want a tidy history.
Rebase and merge: replays the commits onto main without a merge commit.

Follow your team's convention. Afterwards, delete the branch on GitHub (there is a button), then locally:

$ git switch main
$ git pull
$ git branch -d add-site-checklist

If the branch was squash-merged, Git may say it is "not fully merged" because the original commits are not on main. Once you have checked that the PR really was merged on GitHub, git branch -D add-site-checklist deletes it.

Forks

To contribute to a project you cannot push to (most open source), you fork it (copy it to your account), push a branch to your fork, and open a PR from your fork to the original. The review process is the same.

Common mistakes

Opening a PR from main instead of a branch.
Huge PRs mixing several unrelated changes.
Empty descriptions that make reviewers guess.
Closing the PR and opening a new one for every fix, instead of pushing to the same branch.
Forgetting to pull main after merging, then branching from stale code.

Quick recap

Branch, push the branch, open a PR, review, respond with new commits, merge, delete the branch.
Clear title, a what/why/how-to-check description, and small scope.
Review with specific, kind line comments and suggestions; respond, resolve, re-request.

Try it

Open the Do tab to open a PR, review it, and respond to a comment.