Pull request template for GitHub
Fill it in and copy it Open in the editor Opens as pull_request_template.md, ready to edit. Nothing is uploaded.
The shape of it — edit here, or open the full template
Result
Runs entirely in this tab. Open the full editor to work on a real document.
Fill it in and take it
The whole file is below. Type into the boxes to replace the placeholders, then copy it or save it — nothing is sent anywhere, and there is nothing to sign up for.
<!--
.github/pull_request_template.md
GitHub loads this into the description box of every new pull request in the
repository. Keep it short: a template long enough to skim past is a template
people delete without reading.
Comments like this one are invisible in the rendered description, so they can
carry instructions without cluttering the result.
-->
## What this changes
<!-- One or two sentences. What is different after this merges? -->
## Why
<!-- The problem, or a link to the issue. Reviewers who know why can spot a fix
that solves the wrong thing. -->
Closes #
## How to test it
<!-- The steps a reviewer follows to see it working. "Run the tests" is not
enough — say what they should observe. -->
1.
2.
3.
## Screenshots
<!-- Before and after, for anything visible. Delete this section otherwise. -->
## Notes for the reviewer
<!-- Anything that would otherwise arrive as a review comment: a decision you
are unsure about, a file worth reading first, a follow-up you deliberately
left out. -->
## Checklist
- [ ] Tests cover the change, and pass
- [ ] Documentation updated, or not needed
- [ ] No secrets, keys or personal data in the diff
- [ ] Breaking changes called out above
A pull request template is a Markdown file that GitHub loads into the
description box of every new pull request in the repository. Put it at
.github/pull_request_template.md and it applies from the next one opened.
What earns a place in it
Four questions, in the order a reviewer wants them:
What changed. One or two sentences. A reviewer who cannot tell what is different after reading the first line will read the diff with no idea what they are looking for.
Why. The problem, or a link to the issue. This is what catches a change that works but solves the wrong thing.
How to test it. The steps to see it working, and what to observe. “Run the tests” is not a step — the tests run themselves.
Anything the reviewer needs to know. A decision you are unsure about, the file to read first, a follow-up deliberately left out. Everything here is a review comment that never has to be written.
The checklist
Keep it to things that are genuinely checked and genuinely forgettable — tests, documentation, secrets in the diff, breaking changes. A checklist nobody reads is worse than none, because it trains people to tick without looking.
Checkboxes are clickable in the pull request and GitHub shows the count in the list view. They do not block a merge; that needs a required status check.
HTML comments do the explaining
<!-- One or two sentences. What is different after this merges? -->
Comments are invisible in the rendered description, so the guidance is there while someone fills the form in and gone by the time a reviewer reads it. This is the difference between a template that reads as help and one that reads as paperwork.
Several templates
Put each file in .github/PULL_REQUEST_TEMPLATE/ and link to one with
?template=bugfix.md on the compare URL. Worth doing only if something
generates those links — otherwise contributors will never see anything but the
default.
Keep it to one screen
Every section that is routinely left blank teaches the next contributor that the whole thing is optional. Cut anything you do not read. Four headings that get filled in are worth more than twelve that get deleted.
Common questions
- Where does the pull request template file go?
- `.github/pull_request_template.md` is the usual place. GitHub also accepts it in the repository root or in `docs/`, and the filename is case-insensitive. Put it in `.github/` alongside the issue templates and the workflows — that is where the next maintainer will look.
- How do I add more than one template?
- Put each in `.github/PULL_REQUEST_TEMPLATE/` as its own file, then link to one with a `template=` query parameter on the compare URL. Multiple templates are only reachable by that link, so unless something generates those links for you, one good template beats four unused ones.
- Why are there HTML comments in it?
- They give instructions to the author without appearing in the rendered description. A contributor sees the guidance while filling the form in, and the reviewer sees a clean summary. Anything you would otherwise write as "(delete this line)" belongs in a comment instead.
- Do the checkboxes do anything?
- They are clickable in the pull request and GitHub shows the completed count in the list view, so they work as a visible pre-flight. They do not block a merge — for that you need a required status check or a branch protection rule.
- How long should it be?
- One screen. Every section that is routinely left blank teaches the next contributor that the template is optional, so cut anything you do not actually read. Four headings that get filled in beat twelve that get deleted.
- Can I use the same file for issues?
- No — issue templates are separate, live in `.github/ISSUE_TEMPLATE/`, and can be YAML forms with typed fields rather than Markdown. The two are configured independently even though they look similar in the interface.