A pull request (PR) asks your team to review a change and merge it into the main branch. GitLab calls it a merge request, and some companies call it a change list (CL). The quality of your PR decides how fast it gets reviewed and how many bugs the reviewer can catch. A good PR respects the reviewer's time, and that pays you back in faster, better reviews.
Keep it small and focused#
The single biggest thing you control is size. One PR should do one thing. Small PRs are faster to review, easier to reason about and safer to roll back.
- One purpose per PR. A bug fix, a refactor and a new feature are three PRs.
- Separate refactors from behavior changes. A reviewer can approve a pure rename quickly. Mixed with logic changes, it hides the real diff.
- Aim for a size a reviewer can read in one sitting. Google's guidance says about 100 changed lines is usually reasonable, and 1,000 is usually too large.
- Include the tests with the code. Tests belong in the same PR as the change they cover.
Line counts can mislead, though. Generated files, lockfiles and moved files inflate the count. Point them out in the description so the reviewer can skip them.
Write a clear title and description#
A small PR still needs context. The title and description are the first things a reviewer reads, and they should explain the change before the reviewer opens a single file.
Write the title like a commit subject: short, imperative and specific. "Fix timeout in login request" is better than "Login fixes". Then fill in the description with these parts.
| Part | What to write |
|---|---|
| What | One or two sentences on what the change does |
| Why | The problem or ticket it solves, with a link |
| How tested | Unit tests, manual steps, or the environment you checked |
| Risks | What could break, rollout plan, feature flag, migration |
| Screenshots | Before and after, for any UI change |
Leave out parts that don't apply, but always keep What and Why. Many repositories have a PR template that asks for these parts. Fill it in properly instead of deleting it.
Review your own PR first#
Before anyone else reads your diff, read it yourself in the review tool. You'll catch a surprising number of problems this way.
Check for these before you request a review:
- Debug prints, commented-out code and stray TODOs
- Files you didn't mean to change
- Missing tests for new behavior and edge cases
- Names that made sense while coding but not to a new reader
- Confusing logic that needs a short code comment
Add your own comments on lines that need context, such as "This mirrors the retry logic in billing/client.py". Open the PR as a draft if you want early feedback but the work isn't ready to merge.
Stack large changes#
The "keep it small" rule raises an obvious question: what about features that are too big for one small PR? Stacking splits the work into a chain of PRs, where each one builds on the one before. Here's the flow for two parts:
- Create branch
part-1frommainand open PR 1 againstmain. - Create branch
part-2frompart-1and open PR 2 againstpart-1. - Get PR 1 reviewed and merged first.
- Rebase
part-2ontomainand change PR 2's target tomain.
Each PR stays small, and reviewers see one logical step at a time. The cost is extra rebasing when an early PR changes. If PR 1 was squash-merged, use git rebase --onto main part-1 part-2 so that Git skips the old commits. A common order for a stack is data model first, then backend logic, then UI.
Respond to feedback#
Once the review starts, comments come in. They're about the code, not about you, so treat each one as information.
- Reply to every comment. Say "Done", explain why you disagree, or ask a question.
- Push fixes as new commits during review. Reviewers can then see only what changed since their last pass. Squash at merge time if your team does that.
- Explain in the code, not only in the thread. If a reviewer was confused, the next reader will be too. A clearer name or a comment fixes it for everyone.
- Disagree with reasons. Give evidence, such as a benchmark, a doc or a test. If the thread goes back and forth more than twice, talk on a call.
- Let the reviewer resolve their own threads, unless your team has a different rule.
When a review asks for a big redesign, stop and agree on the approach before you write more code. A short design discussion is cheaper than a second large PR.
Keep CI green#
Reviewers aren't the only ones checking your PR. Continuous integration (CI) runs builds, tests and linters on every push, and most teams don't review a PR until CI passes.
- Run the tests and linter locally before you push.
- Fix a red build quickly, or move the PR back to draft.
- Don't retry a flaky test (one that passes and fails at random) until it passes and then ignore it. Report it or fix it.
- Rebase on
mainbefore merge if your branch is out of date, and let CI run again.
A green build tells the reviewer that the basics work. They can then spend their attention on design and correctness.
Key takeaways#
- One purpose per PR, small enough to read in one sitting.
- The description answers what, why, how tested and risks.
- Review your own diff before anyone else does.
- Stack PRs to split large features into reviewable steps.
- Reply to every comment, and fix confusion in the code itself.
- Keep CI green so reviewers can focus on the logic.