A pull request template you can copy today

Every pull request answers the same handful of questions for whoever reviews it. What changed? Why? How do I know it works? A pull request template turns those questions into a form the author fills in, so the reviewer is not left reverse-engineering intent from a diff. On GitHub and GitLab it is nothing more than a Markdown file in the repo, and it appears automatically in the description box when someone opens a new request.

The templates below are ordered from complete to minimal. Copy the one that fits how your team works, then delete anything you would not honestly fill in every time. An unused field is worse than a missing one.

A general-purpose template

This is the workhorse. It covers the summary, the reasoning, the evidence that it works, and a short checklist. It suits most teams and most changes:

## Summary

<!-- What does this PR do, in one or two sentences? -->

## Why

<!-- The problem this solves, or the issue it closes. -->

Closes #

## How it was tested

<!-- The steps you ran, or the tests you added. Be specific
     enough that a reviewer could repeat them. -->

## Screenshots

<!-- Before/after for anything visible. Delete if not relevant. -->

## Breaking changes

<!-- Anything a consumer of this code must change. Write "None"
     if there are none, so the reviewer knows you checked. -->

## Checklist

- [ ] Tests pass locally
- [ ] I added or updated tests for the change
- [ ] Docs updated if behaviour changed
- [ ] No secrets, keys or debug output left in the diff

Two details make this template pull its weight. The Breaking changessection asks for an explicit “None” rather than allowing silence, which forces the author to actually consider the question. And the checklist items are binary: each one is either true or false with no judgement call, which is the single most important property a checklist can have.

A lightweight variant for small teams

On a team of two or three people who trust each other, the full template is friction. The goal shrinks to giving the reviewer context and a single reminder. This is often the right default for a young project:

## What & why

<!-- One paragraph: what changed and the reason for it. -->

## Testing

<!-- How you verified it. A sentence is fine. -->

- [ ] Tests pass
- [ ] Self-reviewed the diff

Notice there are only two checkbox items, and both are things a careful author does anyway. A short template that gets read beats a thorough one that gets skipped.

A bugfix variant

Bug fixes have a different shape from features, and a template tuned to them catches the things that matter for a fix: reproduction, root cause, and a regression test. This one lives well as a named template in the multi-template directory:

## The bug

<!-- What was broken, and how to reproduce it. -->

Fixes #

## Root cause

<!-- The actual cause, not just the symptom. -->

## The fix

<!-- What this change does to address the root cause. -->

## Checklist

- [ ] Added a test that fails without this fix
- [ ] Verified the reported reproduction no longer occurs
- [ ] Considered whether the same bug exists elsewhere

The standout item is the first: a test that fails without this fix. It is the difference between fixing a bug and proving you fixed it, and between a bug that stays dead and one that quietly returns three releases later.

Where the file lives

Placement is what makes the host pick the template up automatically. The rules are simple once you know them.

GitHub, one template

Put a single file at .github/pull_request_template.md. GitHub also accepts it in the repository root or adocs/ folder, but the .githubdirectory keeps meta files out of the way. When a contributor opens a PR, the description is pre-filled with the file’s contents.

GitHub, multiple templates

Create a .github/PULL_REQUEST_TEMPLATE/ directory (note the uppercase name) and drop one Markdown file per template inside it. Contributors select one via a query parameter on the compare URL:

https://github.com/you/repo/compare/main...feature
  ?template=bugfix.md&title=fix:+...

GitLab

GitLab calls them merge request templates and looks in .gitlab/merge_request_templates/. Each Markdown file there becomes a named option in a dropdown when someone opens a merge request. The content works exactly like GitHub’s, only the folder path and the terminology differ.

What makes a checklist actually work

The checklist is where most templates go wrong, so it deserves the most thought. Three properties separate a checklist people use from one they ignore.

• Short. Five items get read. Twenty items get pattern-matched into “check all” without a glance. Every item you add dilutes the ones already there.
• Binary. Each item must be answerable with a clean yes or no. “Tests pass” is binary. “Code is high quality” is an opinion, and opinions do not belong in checkboxes.
• Enforced by reviewers. A template cannot block a merge. Only a reviewer can, by declining to approve until the boxes are honestly ticked. The culture is the enforcement; the template is the reminder.

Templates are a starting point

One thing a template must not become is a form that authors resent. The description box is pre-filled, not locked, and a good author edits it down to what a reviewer actually needs for this change. A one-line documentation typo does not need a testing section and a screenshot slot, and deleting them is exactly what a good author should do.

So write the template for the median PR and trust people to trim it. If you find authors routinely fighting the template, hollowing out sections or ignoring it entirely, that is data: the template is describing more process than the team runs, and it should shrink. When in doubt, cut a section and see if anyone misses it.

It also helps to keep the template close to the other conventions it leans on. A PR that says “Closes #482” only works if issues are tracked; a checklist item about tests only works if tests exist and run in CI. The template is one piece of a repo’s connective tissue, and it reads best next to a clean commit history and current docs rather than in isolation.

The anti-patterns

Watching templates rot teaches the same lessons repeatedly. Avoid these.

The twenty-item checklist is the classic failure. It feels thorough and it is worthless, because a list that long is never read, only bulk-ticked. If a check truly matters, automate it in CI where it cannot be skipped, and keep the human checklist to the handful of things a machine genuinely cannot verify.

The vanity field is the other one: a section nobody fills in that everyone deletes on the way to merging. If a field is empty on nine PRs out of ten, cut it. The template should reflect what your team actually does, not an idealised process it aspires to. A template that describes reality gets used; one that describes a fantasy gets bypassed.

Two related conventions make a template far more useful. Pair it with conventional commitsso PR titles stay parseable (especially on squash-merge teams, where the PR title becomes the commit message), and keep the project’s README current so a reviewer has the context the template assumes.

Frequently asked questions