Pull requests

Status: 🟩 COMPLETE Last updated: 2026-06-20 Plain-English tagline: “I have changes on this branch — please consider merging them into yours.” The unit of code review and the heart of modern Git collaboration.

In plain English

A pull request (PR) is a proposal: “Here’s a branch with some commits; please review and consider merging into the target branch.” PRs are how modern teams (and even solo developers) do code review, run automated checks, link work to discussions, and gate what lands in the main branch.

GitLab calls them merge requests — same idea, different name.

The PR is a structured artifact:

A title (one-line summary)
A description (longer explanation)
A diff (line-by-line changes)
A comment thread (general + per-line)
Reviewers who can approve
Status checks (automated CI runs)
Approvals (formal sign-off)

When all the boxes are ticked, you merge. The branch’s commits become part of the target branch’s history.

Why it matters

Even solo developers benefit from PRs:

A clear review surface. “Did I really only change what I meant to?” The diff makes it obvious.
A target for CI. Vercel deploys a preview; GitHub Actions runs tests; you see results before merging.
A record. Six months later, the PR has the full context of what changed and why.
A pause. The act of opening a PR forces you to summarize and look again.

For teams, PRs are the foundation of code review and the gate that prevents broken code from landing in main.

The structure of a good PR

A well-formed PR:

Title (under ~70 characters)

A clear summary, imperative voice. “Add dark mode toggle,” not “Added dark mode” or “Dark mode toggle implementation.”

Description (the body)

The most valuable part. Should answer:

What changed (one paragraph)
Why (the motivation)
How to test (steps to verify)
Any caveats (known limitations, follow-up work, deferred decisions)

Optional but useful: screenshots for UI changes, links to relevant issues, “Closes #123” to auto-close issues.

A useful template:

## Summary
<one-paragraph what + why>
 
## Changes
- Added X
- Updated Y
- Removed Z
 
## How to test
1. Open the dev server
2. Click the toggle in the navbar
3. Confirm both modes work and persist across reload
 
## Notes
- Doesn't yet handle system-preference detection — follow-up PR

The diff

The actual changes, automatically generated. Reviewers read it line by line.

Status checks

Automated stuff that runs on every push to the PR branch: tests, builds, linting, security scans, Vercel preview deploys. Each appears as a check at the bottom.

Reviews

People can leave comments (general or per-line), request changes, or approve. Branch protection rules typically require at least one approval before merge.

A concrete example: opening a PR

After committing and pushing your branch:

gh pr create \
  --title "Add dark mode toggle" \
  --body "$(cat <<'EOF'
## Summary
Add a dark/light mode toggle to the navbar. Preference persists in localStorage and respects system preference on first load.
 
## Changes
- Added `lib/theme.ts` with theme provider
- Added `ThemeToggle` component in navbar
- Added dark variants to color classes in `globals.css`
 
## How to test
1. `npm run dev`
2. Open http://localhost:3000
3. Click the moon/sun icon in the navbar
4. Reload — toggle should remember the choice
 
## Notes
- Doesn't sync across tabs yet (future enhancement)
EOF
)"

Or via the GitHub web UI: navigate to the repo, click “Compare & pull request” when GitHub detects the new branch, fill in the form.

The PR is now open. Vercel will deploy a preview, Actions will run, reviewers get notified.

The review cycle

After opening:

CI runs. Wait a minute or two; check that all status checks pass.
Reviewers read. They leave comments — general or per-line. Per-line is shown inline at the relevant code.
You address comments. Make changes locally, commit, push. The PR auto-updates with new commits. Reply to comments to explain or push back.
Re-request review. Once you’ve addressed comments, formally re-request review.
Approval. Reviewers click “Approve” when satisfied.
Merge. When approved and checks pass, the merge button is enabled. You (or a maintainer) clicks merge.

Merge strategies (again, from PR perspective)

When you click merge, GitHub asks you which strategy:

Strategy	What it does	When to use
Create a merge commit	Preserves branch history + adds a merge commit	When you want the branch structure visible
Squash and merge	All branch commits collapse into one commit on main	Default — keeps main linear and clean
Rebase and merge	Re-applies branch commits onto main (no merge commit)	When you want linear history but preserve individual commits

Most teams (and solo workflows) default to Squash and merge. The PR description becomes the squashed commit message, which is usually exactly the summary you want in main’s history.

”Closes #123” — linking issues

If your PR resolves an issue, put Closes #123 (or Fixes, Resolves) in the description. When the PR merges, the linked issue auto-closes. The PR also gets a backlink from the issue.

Useful for tracking work units across discussions and changes.

Drafts

You can open a PR as a draft — visible but not ready for review. CI still runs. Reviewers know not to spend time yet.

Mark as ready for review when you want eyes. Useful for:

WIP work you want CI to validate
Early sharing of approach for feedback
Long-running PRs you want to “park” temporarily

Branch protection rules

In your repo’s settings, you can configure rules on specific branches (typically main):

Require at least N approvals
Require status checks to pass
Require branches to be up to date with main before merging
Restrict who can push
Require linear history (no merge commits)
Require signed commits

For solo work, these are optional but worth setting up — they prevent accidental direct pushes.

For team work, they’re how you enforce the workflow.

CI status checks — what to expect

For a Next.js + Vercel + Supabase project, typical checks are:

Vercel preview deployment — every PR gets its own URL
Build success — Vercel runs npm run build
Type checking — tsc --noEmit (if you’ve set up the workflow)
Linting — eslint (if configured)
Tests — npm test (if you have any)
Security scans — Dependabot, CodeQL (auto-enabled on public repos)

Each appears as a row at the bottom of the PR. Green checkmark = passed; red X = failed. Failed checks block merge if protection is enabled.

A typical solo-developer flow

Even for one person:

git switch main
git pull
git switch -c feature/new-thing
# ... work ...
git push -u origin feature/new-thing
gh pr create --title "Add new thing" --body "..."
# Wait for Vercel preview, click through to test
# If all good — merge
gh pr merge --squash
git switch main
git pull
git branch -d feature/new-thing

The PR step costs you ~30 seconds of friction. In exchange you get: an automatic preview deploy, a CI run, a review surface, and a permanent record. Worth it.

Common gotchas

Vague titles and descriptions. “Fix bug” tells future-you nothing. “Fix infinite loop in chat scroll on mobile” tells everything.
Huge PRs. A 500-line diff is hard to review well. Split big work into multiple PRs when you can.
Force-pushing while a review is in flight. Reviewers’ comments may attach to old line numbers; force-push can scramble them. Try not to force-push after review starts; if you must, communicate.
Merging your own PR without review. For solo work, fine. For team work, defeats the purpose. Most teams enforce at least one approval.
Forgetting to update the PR description after big changes. The description should reflect the current state of the PR, not the original idea.
Conflicts after main moves. If main changes while your PR is open, you may need to merge main into your branch (or rebase) before GitHub will let you merge.
Auto-merge surprises. GitHub’s “auto-merge” feature merges your PR as soon as conditions are met — even after you walk away. Useful but verify before enabling.
Stale PRs. PRs that sit for weeks accumulate conflicts and slip in priority. Close them or merge them; don’t let them rot.
PR templates. If your repo has a .github/PULL_REQUEST_TEMPLATE.md, GitHub auto-fills new PR descriptions with it. Useful for enforcing structure.
Reviewing your own PR before publishing. GitHub shows you the diff as soon as you push. Read it as if you were the reviewer; you’ll catch things.

Tech & AI, Explained

Explorer

pull-requests