What a pull request is
A pull request is a formal request to merge the changes on one branch into another, usually the team’s main branch. It is a feature of hosting services rather than of Git itself: Git provides branches and merges, while the hosting service wraps them in a page where people can read the proposed changes, comment on individual lines, discuss them and eventually approve. Some services use other names, such as merge request, but the idea is the same.
The word “pull” comes from the original sense of asking the maintainer to pull your changes into their copy. In practice you push your branch to the shared repository, open the request, and your colleagues review before anything is merged.
Why teams use them
A pull request gives a team a checkpoint before work joins the main line. It serves several purposes at once.
- Review. A second person reads the change and may spot mistakes, unclear naming or missing cases. The practice of code review is a skill in its own right.
- Discussion. Questions and decisions happen next to the exact lines they concern, and stay on record.
- Automated checks. Many teams run tests and style checks on each request, which is where continuous integration often shows up.
- Knowledge sharing. Reviewers learn what is changing, and authors learn from feedback. This is one of the easiest forms of knowledge sharing a team has.
- A written record. Months later, the request explains why a change was made and who agreed to it.
Not every project needs the ceremony. For a solo project, direct commits may be enough. For anything shared, or anything where a mistake is costly, the checkpoint is usually worth its small overhead.
Before you open one
A lot of review friction can be avoided before anyone else sees the request.
- Read your own diff first. Look at it as a reviewer would. You will often find leftover debugging lines, stray files or unintended edits.
- Run the tests and builds. Do not ask someone to review something that does not build.
- Bring your branch up to date. Merge or rebase the latest main branch changes so that conflicts are resolved by you, not by the reviewer.
- Check the commits. Are they sensibly grouped, with good messages? If your branch has messy work-in-progress commits, tidy them while the branch is still only yours.
- Remove unrelated changes. Formatting fixes or renames unrelated to the main purpose belong in a separate request.
Keep it small and focused
The single biggest factor in review quality is size. A short change can be understood in a few minutes, and reviewers can be thorough. A change touching dozens of files tends to get a quick glance and an approval, because reading it properly is too much work. That is the opposite of what the review is for.
As a rough habit, aim for one purpose per request. If you find yourself writing “and also” in the description, consider splitting it. If a large change is unavoidable, such as a file move, say so, and consider separating mechanical changes from logical ones so reviewers can concentrate on the logic.
Write a clear title
The title should say what the change does, in the same style you would use for a good commit message. Compare:
- Weak: “Updates”
- Better: “Add retry on failed sensor reads”
A reviewer scanning a list of open requests should be able to tell, from titles alone, which ones concern them.
Write a useful description
A good description answers the questions a reviewer would otherwise have to ask. A simple structure works well:
- What and why. Summarise the change and the problem it solves in a few sentences. Link or mention the related ticket if you have one.
- How. Describe the approach briefly, especially if you considered alternatives or made a non-obvious choice.
- How it was checked. Say what you tested and how, including anything you could not test.
- What to look at. Point reviewers to the parts you are least sure about, or the files that matter most.
- Anything surprising. Mention changes in behaviour, new settings, or steps others must take after merging.
Where the change is visible, a before-and-after screenshot or a short output sample helps. Keep the writing plain: short sentences, no private jargon, and the same clarity you would aim for in any technical writing.
Some teams use a template that pre-fills these headings. That is a good way to make the habit stick.
While it is under review
- Respond promptly and politely. A reviewer’s comment is about the code, not about you. Receiving review feedback gracefully is part of the process.
- Ask when a comment is unclear. Do not guess what was meant.
- Explain, don’t defend. If you disagree, give your reasoning calmly, and be willing to be persuaded. Technical disagreements are easier to settle with evidence than with opinions.
- Push follow-up commits to the same branch to address comments, and say what you changed. Hosting services update the request automatically.
- Mark settled discussions so everyone can see what is left to do.
Reviewers help too
If you are the reviewer, read the description first, check the tests, and comment on what matters most. Say what is good as well as what needs changing, and distinguish required fixes from suggestions. Review promptly, since a request waiting for days blocks the author and lets the branch drift away from the main line.
Merging
When the request is approved and checks pass, someone merges it. Teams differ on the method: some keep every commit, some squash the branch into one commit, and some rebase. Whichever you choose, agree on it and apply it consistently so the history stays readable. After the merge, delete the branch, and confirm that the main line still builds.
Policies on who must approve changes can matter a great deal in regulated or safety-related work. Those rules vary by country and industry, so follow the requirements of your organisation rather than the habits described here.