This template gives you those sections with placeholders and a checklist. Save it as .github/pull_request_template.md, adjust the checklist to your project's rules, and commit it to the default branch.
Need it as a document? Paste the filled-in template into the free Markdown to Word or Markdown to PDF converter.
Pull request template key facts
- Name the file
pull_request_template.mdand put it in the repository root, thedocsfolder, or the hidden.githubfolder. - Pull request template filenames are not case sensitive and can use an extension such as
.mdor.txt. - Templates must be on the repository's default branch. Templates on other branches are not available to collaborators.
- For several templates, create a
PULL_REQUEST_TEMPLATEsubdirectory in one of those folders and choose a template with thetemplatequery parameter. - GitHub Docs suggests including a reference to a related issue, a description of the changes, and @mentions of the people responsible for reviewing.
- A keyword such as
Closes #123links the issue, but it only closes the issue automatically when the pull request targets the default branch. - A public repository named
.githubcan hold a default pull request template for every repository in the account that does not have its own.
Copyable Markdown pull request template
## Summary
[Describe what this pull request changes and why. One short paragraph is enough. Link to a design document or discussion for background.]
## Related issue
Closes #[issue number]
<!-- "Closes" closes the issue automatically only when this pull request is merged into the default branch. Use "Related to #123" if the issue should stay open. -->
## Type of change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (existing behavior changes or is removed)
- [ ] Documentation
- [ ] Refactoring, maintenance, or dependency update
## How this was tested
[Describe the tests you ran and how a reviewer can reproduce them.]
```bash
[test command]
```
- **Test environment:** [Operating system, browser, runtime, or device]
- **Manual checks:** [Steps you followed and what you confirmed]
## Screenshots
[For visible changes, add before and after screenshots. Delete this section if it does not apply.]
| Before | After |
|---|---|
| [Screenshot] | [Screenshot] |
## Checklist
- [ ] I have read the contributing guide (CONTRIBUTING.md).
- [ ] This pull request contains one logical change.
- [ ] I added or updated tests that cover the change.
- [ ] I updated the documentation for any changed behavior.
- [ ] I added an entry under `## [Unreleased]` in CHANGELOG.md for user-facing changes.
- [ ] All checks pass locally and in CI.
## Notes for reviewers
[Point out anything that needs attention: risky areas, follow-up work, open questions, or files that can be skimmed. Mention reviewers with @username if your project does not assign them automatically.]
What a pull request description should answer
A reviewer opens a pull request with three questions: what is this, why is it needed, and how do I know it works? The template answers them in that order.
- What changed? The Summary section, in a few sentences.
- Why? The linked issue, which holds the original problem and discussion.
- How risky is it? The type of change, especially whether it is a breaking change.
- How was it verified? Test commands, environments, and manual checks a reviewer can repeat.
- What should the reviewer look at closely? Notes for reviewers.
Delete sections that do not apply to a given pull request. A Screenshots table with placeholder text adds noise.
Linking issues with closing keywords
GitHub recognizes these keywords followed by an issue reference in a pull request description: close, closes, closed, fix, fixes, fixed, resolve, resolves, and resolved. When the pull request is merged into the default branch, the linked issue closes automatically.
The keywords are interpreted only when the pull request targets the default branch. If your project merges into a development or release branch first, the issue stays open after the merge. In that workflow, link the issue with a keyword anyway for traceability and close the issue when the change reaches the default branch, or link it manually from the sidebar.
Multiple pull request templates
Some projects want different templates for features, bug fixes, and releases. Put each file in a PULL_REQUEST_TEMPLATE subdirectory, for example:
.github/
PULL_REQUEST_TEMPLATE/
feature.md
bug_fix.md
release.md
Then add the template query parameter to the URL that opens the pull request:
https://github.com/[owner]/[repository]/compare/main...[branch]?quick_pull=1&template=bug_fix.md
Put these links in CONTRIBUTING.md so contributors can find them. A single pull_request_template.md with sections people delete when they do not apply is simpler and works for most projects.
Completed pull request example
## Summary
Retry failed uploads up to three times with exponential backoff.
Uploads on unstable connections previously failed on the first timeout.
## Related issue
Closes #482
## Type of change
- [x] Bug fix (non-breaking change that fixes an issue)
## How this was tested
npm test
Manual: throttled the network to 3G in browser dev tools and uploaded
a 20 MB file. The upload retried twice and completed.
## Checklist
- [x] I added or updated tests that cover the change.
- [x] I added an entry under "## [Unreleased]" in CHANGELOG.md.
- [x] All checks pass locally and in CI.
The example states the change and its reason in two sentences, links the issue, and describes a test a reviewer can repeat. The issue number and details are fictional.
What to include in a pull request template
| Section | What to write |
|---|---|
| Summary | What changed and why |
| Related issue | Closes #123 or Related to #123 |
| Type of change | Bug fix, feature, breaking change, documentation, maintenance |
| Testing | Commands, environments, and manual checks |
| Screenshots | Before and after for visible changes |
| Checklist | Contributing guide, tests, docs, changelog, passing checks |
| Notes for reviewers | Risky areas, open questions, follow-up work |
Pull request template FAQ
Where do I put a pull request template on GitHub?
Save it as pull_request_template.md in the repository root, the docs folder, or the .github folder, and merge it into the default branch. It then appears in the description of every new pull request.
Can I have more than one pull request template?
Yes. Put the templates in a PULL_REQUEST_TEMPLATE subdirectory and select one with the template query parameter, for example ?quick_pull=1&template=bug_fix.md.
Why does "Closes #123" not close my issue?
Closing keywords only work when the pull request targets the repository's default branch. If the pull request is merged into another branch, close the issue manually or after the change reaches the default branch.
Should a pull request template include a checklist?
A short checklist helps contributors confirm the steps your project requires, such as tests, documentation, and a changelog entry. Keep it to items reviewers actually check.
What is the difference between a pull request template and CONTRIBUTING.md?
CONTRIBUTING.md explains the full contribution process: setup, branching, style, and review. The pull request template is the form a contributor fills in for one change. Link the contributing guide from the template's checklist.
Related templates
- GitHub issue template
- CONTRIBUTING.md template
- CHANGELOG.md template
- SECURITY.md template
- CODE_OF_CONDUCT.md template
- README template
- Bug report template
- All Markdown templates