Pull Request Template: What Reviewers Need

A good pull request template asks for six things: the task the change is for, what changed, why it changed that way, how it was tested, what is risky or needs a close look, and how to roll it out or back. Keep it short enough that authors fill it in rather than delete it, put it in the file your code host reads (.github/pull_request_template.md on GitHub), and link the task by its reference so anyone can get from the code to the reason for it. Everything else, such as formatting and passing tests, belongs in CI, not in a checkbox.

The template is the author’s half of the review. The reviewer’s half is the code review checklist, and each section below exists because a line on that checklist needs it.

What reviewers need from a pull request

A reviewer opening a pull request has four questions before reading a line of code: what is this for, what should I look at first, how do I know it works, and what happens if it is wrong. A diff answers none of them. A description that does turns a thirty-minute review into ten, and stops the round trip of “what is this for?” that costs the author a day.

The sections, and why each is there

Task

One line: the reference of the work item and its title. It lets the reviewer read the original problem and acceptance criteria, and it lets anyone who finds this code in a year trace it back to why it exists. If there is no task, that is worth asking about in itself.

What changed

Two to five bullets in plain words, describing behavior rather than files: “Checkout now rejects expired cards before calling the payment provider,” not “Updated CheckoutService.ts.” Mention anything deliberately left out, so the reviewer does not flag it as missing.

Why this way

Only when the approach is not obvious: the alternative you tried and rejected, the constraint that forced an odd choice. This is the section that saves the longest comment threads. Larger choices deserve an architecture decision record that the pull request links to.

How it was tested

What was run and what was checked by hand, with the result, and what was not checked. “Unit tests pass; checked on staging in Chrome and Safari on iPhone; not checked with a real payment” is useful. “Tested” is not. Screenshots or a short screen recording for anything visual.

Risk and where to look

Point the reviewer at the part you are least sure of. Flag anything that touches sign-in, permissions, payments, personal data or a database migration, because those get a second reviewer on most teams.

Rollout

Anything that has to happen outside the merge: a migration to run first, a feature flag to turn on, a config value to set, and how to undo it if it goes wrong. Leave it as “None” when there is nothing; that is an answer too.

A pull request template to copy

## Task
<!-- Ref and title, e.g. BUG-142: Checkout accepts expired cards -->

## What changed
<!-- 2-5 bullets, in terms of behavior. Note anything left out on purpose. -->
-

## Why this way
<!-- Only if not obvious: alternatives rejected, constraints. Else delete. -->

## How it was tested
<!-- What you ran, what you checked by hand, results. Say what you did NOT check. -->
- Automated:
- Manual:
- Not checked:

## Risk / where to look
<!-- The part you are least sure of. Flag auth, payments, personal data, migrations. -->

## Rollout
<!-- Migrations, flags, config, and how to undo. "None" is fine. -->

## Screenshots
<!-- For UI changes: before and after. Else delete. -->

Notice what is missing: no “I have followed the style guide” checkbox, no “tests pass” checkbox. Checkboxes an author can tick without doing anything get ticked without anything being done. If something must be true on every change, enforce it in CI or branch protection. Microsoft’s documentation for Azure Repos makes the same point: templates “are advisory only,” and branch policies are what enforce requirements.

Scale the description to the change

A template is a prompt, not a form to be filled in completely every time. A one-line typo fix needs the task ref and a single bullet; the other sections can be deleted. A change to how refunds are calculated needs every section, and probably a longer “Why this way” than the template suggests. A useful rule for authors: write the description you would want if you were reviewing this change on a Friday afternoon with no memory of the task. If the reviewer still has to ask what the change is for, how it was tested or what could break, the description was too short, whatever the template said.

Where the file goes

• GitHub: pull_request_template.md in the repository root, docs/ or .github/. For several templates, put them in a .github/PULL_REQUEST_TEMPLATE/ folder and choose one with the template query parameter. GitHub’s documentation↗ (opens in a new tab) notes templates are available once they are merged into the default branch.
• GitLab calls them merge request description templates: Markdown files in .gitlab/merge_request_templates/. A file named Default.md is used by default, but GitLab’s documentation↗ (opens in a new tab) notes that a default set in project settings takes priority over it.
• Azure DevOps: pull_request_template.md or .txt in .azuredevops/, .vsts/, docs/ or the root, on the default branch. Azure Repos↗ (opens in a new tab) also supports branch-specific templates under pull_request_template/branches/, so pull requests into a release branch can get a stricter template.

Linking the task ref

The task line is the one that pays off for years, so make it easy to follow. If your tasks are GitHub issues, a closing keyword such as Fixes #142 links the pull request to the issue and closes it on merge; GitHub’s documentation↗ (opens in a new tab) lists the keywords and notes they are interpreted only when the pull request targets the default branch.

If your tasks live in another tracker, GitHub’s autolink references↗ (opens in a new tab) turn a prefix into a link: a repository admin sets a prefix such as BUG- and a target URL containing <num>, and every BUG-142 in a pull request, issue or commit message becomes a link. Put the ref in the branch name and the commit message as well, so it can still be found whichever way the branch is merged.

On fenbs, a task’s ref shows its kind: FET- for a feature, ENH- for an enhancement, BUG- for a bug. Refs are numbered per board and never reused, even after a delete, so a ref quoted in a pull request keeps meaning the same task. Only the digits are matched, so if someone later changes a bug to a feature and BUG-142 becomes FET-142, a search for the old ref still finds it. fenbs does not connect to GitHub or read your pull requests, so the link runs one way: put the pull request link, or the merge commit, in a comment on the task when you move it to Completed, and record how it was tested in the task’s test status and notes. Then the board answers “what shipped and was it checked?” without anyone opening the code host.

When an AI assistant opens the pull request

Do not assume a coding agent that opens a pull request will fill in your template the way a person would: tell it to. The sections matter more, not less, when an agent wrote the change: “How it was tested” and “Not checked” are where an agent’s claims become something a reviewer can verify. Add a line to your instructions file telling the agent to fill every section, quote the test command and its output, and put the task ref first. AGENTS.md examples shows where that line goes, and how to review AI-generated code covers what the reviewer does with it.

Keep the template alive

• Review it every few months. Any section that is always deleted or always says “N/A” should go.
• When a review keeps asking the same question, add a section that answers it.
• Keep one default template. Extra ones for releases or hotfixes are fine, but every template is one more thing to keep current.
• Changes to the template go through review like code, because they change what every future review sees.