Feature Branches and Pull Requests

This is the core working rhythm. Every change — every single one — follows the same loop: branch → commit → pull request → review → merge.

graph LR
  M[main branch] --> B[your branch]
  B --> P[Pull Request]
  P --> R[Review]
  R --> M

What a feature branch is

A branch is a private workspace where you can change anything without affecting anyone else. The main branch is the shared, trusted version that everyone deploys from. Think of it like editing a Google Doc in "suggesting" mode — your edits exist, but nobody else's view of the document changes until someone accepts them.

What the main branch should always contain

The rule of thumb: main should always contain a working version of the software in this repo. Not a perfect version, not a bug-free version — bugs will sneak in, that's normal — but a version that runs and behaves roughly as expected.

Why this matters: anyone, at any time, can take whatever is currently on main, build it, and release it. If main is broken, everybody is blocked. That's why we use feature branches: experimental, half-finished, or risky work happens off to the side until it's ready.

Naming your branch

Branch names should be short and describe the change — something like your-name/short-description or feat/add-export-button is typical. Claude Code will suggest a name when you ask it to create a branch; you can usually accept its suggestion. The exact convention varies by team, so when in doubt, look at recent branches in the repo and follow the pattern.

What a Pull Request is

A Pull Request (PR) is your formal proposal: "I'd like these changes merged into main." It lives on GitHub and contains:

A title and description (what and why).
The diff (what changed).
A space for reviewers to comment.
Automatic CI checks (see the next article).

Writing a good PR description

A good PR description includes:

One sentence on why this change exists.
A note on anything reviewers should look at carefully.
Screenshots if you changed something visible.

Claude Code can draft the description for you, but read it before submitting — it sometimes overstates what was done or invents context.

Before asking for review

Reviewers' time is the most expensive resource in this process — don't waste it. Before you tag someone or click "Request review", make sure:

All PR checks are passing (green ✅, not red ❌ or yellow 🟡). If CI is failing, fix it first. Asking for review on a broken PR signals that you haven't checked your own work.
Any merge conflicts are resolved. A merge conflict means your branch has fallen out of sync with main and the two versions disagree about the same lines. GitHub will show a banner when this happens — pull the latest main into your branch and resolve the conflict before requesting review.
You've re-read your own diff at least once. Half the comments a reviewer would have left, you'll catch yourself.

A useful rule of thumb: a PR is ready for review when you'd be happy for it to be merged exactly as it is, right now. If you're still planning to clean things up "before merge", you're not ready yet.

Code review — what to expect

A reviewer is not judging you. They're a second pair of eyes catching things you and the AI both missed. Expect comments. Address them, push another commit, and the PR updates automatically.

The philosophy of PR reviews

This is the part people most often get wrong, so it's worth stating plainly.

The author of the PR owns the change. If something breaks in production, the answer to "who is responsible?" is the person who opened the PR — not the reviewer, not Claude Code, not the CI system. You proposed it; you stand behind it.

Reviewers hold you accountable. Their job is not to take responsibility off your shoulders. Their job is to ask the awkward questions, point out what looks wrong, and push back when something doesn't smell right. A reviewer who silently approves everything isn't being kind — they're failing you.

What this means in practice:

Don't merge a PR just because a reviewer approved it. If you are not confident the change is correct, ask for more review or do more testing.
Don't take review comments personally. A reviewer pushing back is the system working as intended. Engage with the substance, not the tone.
As a reviewer, don't rubber-stamp. If you don't understand what the change does, say so. "I'm not sure what this does — can you explain?" is a valid and useful review comment.

The goal isn't to catch every bug before merge — that's impossible. The goal is to make sure that whoever proposed the change has thought it through, and that a second person has at least looked at it with fresh eyes.

When it's ready

Once approved and CI is green, you (or someone with permission) clicks Merge. Your branch disappears, and your change is now part of main. The next article covers what happens next — automatically.