paulund

Creating Pull Requests

Creating Pull Requests

A pull request is the primary mechanism for proposing, discussing, and integrating changes. The way you structure and present a pull request has a direct impact on how quickly and confidently it gets reviewed and merged.

Keep Pull Requests Small

When creating a pull request, keep it small. A focused PR is easier for a reviewer to understand, easier to test, and easier to roll back if something goes wrong. If you have a large change to make, break it into a sequence of smaller pull requests that can be reviewed and merged independently.

Small pull requests also increase confidence. A reviewer who can take in the full scope of a change in one sitting is far more likely to spot problems and approve with conviction. A 2,000-line diff, by contrast, invites rubber-stamping.

You can use a technique called daisy-chaining (also known as stacked PRs) to break up a large feature into a series of pull requests that build on each other. Each PR targets the branch of the previous one rather than main directly. GitHub updates the base branch automatically as earlier PRs are merged. See the stacked pull requests guide for full details.

Use Descriptive Titles

The title is the first thing a reviewer reads. Make it clear and concise — it should tell the reviewer what the change does and, where possible, why.

A good title is short (under 70 characters) and written in the imperative mood:

Add password reset flow for local accounts
Fix race condition in cart line-item creation
Refactor invoice generation into its own service

If your team uses an issue tracker such as Jira or Linear, include the ticket reference. This makes it trivial to trace a change back to its original requirement:

[PROJ-142] Add password reset flow for local accounts

Write a Useful Description

The description is where you give the reviewer context that the code alone cannot provide. Cover:

  • What changed and why — not a line-by-line summary of the diff, but the reasoning behind the change.
  • How to test it — steps the reviewer can follow to verify the change manually if automated tests do not cover the scenario fully.
  • Any risks or trade-offs — flag anything that might surprise the reviewer or that you are unsure about.

Use a Pull Request Checklist

Every team has different expectations for what a pull request should contain. When you join a new project, create a personal checklist of the things you need to verify before opening a PR — tests pass, documentation is updated, no debug code left in, and so on. Over time, refine this checklist as you learn the project's conventions.

You can codify it as a GitHub pull request template so that every PR in the repository starts with the same structure. This nudges every contributor to think through the same set of concerns.

Review Your Own Pull Request First

GitHub's draft pull request feature is useful here. Create the PR as a draft before you mark it as ready for review. This lets you:

  • See your own changes exactly as a reviewer will see them — diffs, file trees, and all.
  • Catch small errors like typos, leftover debug statements, or missing imports before another person's eyes land on them.
  • Request early feedback on the approach without implying the code is finished.

Reviewing your own work before handing it to others is one of the highest-return habits in software development. It takes two minutes and saves everyone time.