How to Write a Pull Request Template (With Copy-Paste Examples for 2026)

What a pull request template actually does

A pull request template is a Markdown file your version-control host pre-loads into the description box every time someone opens a PR. Instead of an empty text area that invites a one-line “fixed the thing,” the author sees a structured prompt asking what changed, why, and how it was tested.

The value is not the file itself - it is the behavior it shapes. A good template moves the cost of understanding a change from the reviewer to the author, at the exact moment the author has the most context. It also front-loads the questions a reviewer would otherwise have to ask in a comment thread, which is the slowest possible place to ask them. The takeaway - a template’s job is to make the author write down what the reviewer would have had to reverse-engineer.

For the underlying mechanics of the object itself, see our pull request glossary entry.

Where the template file lives

On GitHub the loader checks three locations, in this order of convention:

• The repository root - pull_request_template.md
• A .github/ folder - .github/pull_request_template.md (the tidiest and most common)
• A docs/ folder - docs/pull_request_template.md

The filename is case-insensitive. GitLab uses .gitlab/merge_request_templates/*.md, and Azure DevOps and Bitbucket have their own equivalents, but the principle is identical everywhere. Commit the file to your default branch and it takes effect on the next PR.

The takeaway - a single template belongs in .github/pull_request_template.md; that is the path nearly every repo uses and the one contributors expect.

Multiple templates for different change types

One template rarely fits every PR. A hotfix does not need a design-review section; a schema migration desperately needs a rollback plan. GitHub supports this through a directory:

.github/
  PULL_REQUEST_TEMPLATE/
    feature.md
    bugfix.md
    hotfix.md

Contributors select one by appending a query parameter to the compare URL:

https://github.com/acme/api/compare/main...my-branch?template=bugfix.md

A common pattern is to keep a lightweight default at .github/pull_request_template.md and reserve the directory for the two or three change types that genuinely need bespoke prompts. Do not build eight templates - the selection friction outweighs the benefit.

Copy-paste template examples

These are starting points. Delete sections that do not earn their place on your team, because every unused field trains authors to ignore the template.

General-purpose template

## What & why
<!-- One or two sentences. What does this change do and why now? -->

## Type of change
- [ ] Bug fix
- [ ] New feature
- [ ] Refactor (no behavior change)
- [ ] Docs / chore

## How I tested this
<!-- Commands run, cases covered, screenshots for UI. -->

## Checklist
- [ ] PR is under ~250 lines of meaningful change
- [ ] Tests added or updated
- [ ] No secrets, keys, or debug logging left in
- [ ] Linked the related issue below

Closes #

Bug-fix template

## The bug
<!-- What was broken? Link the issue or incident. -->

## Root cause
<!-- Why did it happen? This is the most valuable box on the page. -->

## The fix
<!-- What did you change, and why this approach? -->

## Regression guard
- [ ] Added a test that fails without this fix
- [ ] Verified the original reproduction no longer occurs

Feature / rollout template

## Summary
## Design notes
<!-- Alternatives considered, tradeoffs, links to the design doc. -->

## Rollout & rollback
- [ ] Behind a feature flag
- [ ] Safe to roll back with no data migration, OR migration is reversible
- [ ] Monitoring / alerts in place

## Reviewer guidance
<!-- Where should the reviewer focus? What is low-risk boilerplate? -->

That last “reviewer guidance” box is underrated - it lets the author point the reviewer at the two files that matter and wave them past the generated ones, which is the fastest way to raise review depth without lengthening the review.

The parts that matter most

Across every template above, three sections carry the weight:

Section	Why it earns its place
Why now	Reviewers approve intent as much as code. Context prevents “why does this exist” threads.
How I tested	Separates verified changes from hopeful ones and sets the reviewer’s trust level.
Checklist	A pre-flight the author runs on themselves - catches the obvious before a human looks.

Keep the checklist short and binary. Items a bot can verify - lint passed, tests green - belong in CI, not on a human checklist. Reserve the checklist for judgment calls a machine cannot make, like “I confirmed this migration is reversible.”

The takeaway - if a checklist item can be automated, automate it and remove it from the template; the human list should hold only things a machine cannot check.

How to actually enforce it

Here is the hard truth - GitHub pre-fills a template but never forces anyone to complete it. Left unenforced, a template decays into boilerplate that authors clear with a single keystroke. Two mechanisms fix that:

1. A required status check. Add a CI job or a small bot that parses the PR body and fails if required sections are blank or the checklist is unticked, then make it a required check under branch protection. Now an incomplete PR literally cannot merge.
2. Automated review that reads the template. AI reviewers can treat your template as intent and flag drift from it.

CodeRabbit generates a PR summary automatically and accepts custom review instructions in natural language, so you can tell it to check that the “how I tested” section is filled in and comment when it is not (source - CodeRabbit tool page). That turns a passive template into an active gate.

Graphite approaches it from the workflow side - it can generate PR descriptions automatically and enforce custom review rules and automations across every repo in your GitHub org, so template conventions hold up at scale rather than depending on each author’s discipline (source - Graphite tool page).

Common template mistakes

• Too long. A template that scrolls gets deleted. Aim for something an author completes in under a minute.
• Redundant with CI. Do not ask a human to confirm “lint passes” - your pipeline already knows.
• No enforcement. An unenforced template is a suggestion, and suggestions erode.
• One template for everything. A hotfix and a schema change need different prompts; use the directory pattern.
• Comment cruft left in. Authors often forget to delete <!-- ... --> hints. A linter or bot can flag leftover placeholder text.

Conclusion

A pull request template is one of the cheapest process wins available - a single Markdown file that shifts the work of explaining a change onto the person best placed to explain it. Put it at .github/pull_request_template.md, keep it short, split it by change type only where that genuinely helps, and enforce it with a required check so it cannot rot into boilerplate. Pair it with a solid code review checklist and clear norms for giving review feedback, and your reviews start from shared context instead of an empty box.

Further reading

• Code Review Checklist for Authors and Reviewers
• How to Give Code Review Feedback That Lands
• Pull Request Size Best Practices
• The Complete GitHub Pull Request Review Guide
• Code Review Best Practices