Reviewers are reading your story

A pull request is a story you tell about a change. Before opening it, take five to ten minutes to clean up the narrative. The result: faster reviews, fewer follow-up commits, and a history future-you will be glad to read.

Step 1: rebase onto main

git fetch origin
git rebase origin/main

Resolve any conflicts now, while the change is fresh. Reviewers should not see a merge commit from main in your branch.

Step 2: squash WIP commits

If your branch is littered with "wip", "more wip", and "address PR feedback", consolidate them:

git rebase -i origin/main

Mark noise commits as fixup or squash into their logical parent.

Step 3: rewrite messages

Use reword in interactive rebase to fix typos, expand context, and ensure each commit explains why the change was made.

Step 4: re-run tests and linters

npm test
npm run lint
npm run typecheck

Rebasing can cause subtle breakage; rerun the full suite before pushing.

Step 5: self-review the diff

git diff origin/main...HEAD
git log origin/main..HEAD --oneline

Read every line as a hostile reviewer. Did you leave a console.log? A debug flag set to true? A commented-out experiment? Strip them now.

Step 6: check for secrets

git diff origin/main...HEAD | grep -iE 'password|secret|api[_-]?key|token'

Use gitleaks or trufflehog for thorough scanning. A secret committed and pushed is a secret leaked.

Step 7: verify the build

Push to a draft PR or run CI locally if possible. Discovering a CI failure after reviewers start commenting wastes everyone's time.

Step 8: write the PR description

Include: what changes, why, how you tested, screenshots if UI, and any risks or follow-ups. A good PR description references the ticket, lists the smallest non-obvious decisions, and tells the reviewer where to look first.

Step 9: force-push with care

git push --force-with-lease origin feature/login

If the branch is yours alone, force-with-lease is safe. If someone else commits to your branch (rare but possible), --force-with-lease refuses the push instead of overwriting their work.

Step 10: keep the PR small

If your diff is more than 400 lines or touches more than 10 files, consider splitting. Reviews of large PRs are statistically less thorough; split into stacked PRs instead.

Five minutes of cleanup turns a PR from a chore into a pleasure to review. The investment compounds.