GitPR Templates

Pull Request Templates

A PR template is a markdown file checked into your repo that GitHub uses to pre-fill the description box every time a PR is opened. It’s the cheapest way to enforce a team standard — instead of nagging people to fill in “what / why / how to test”, the template just appears, and most people fill it in.

Where to put the template

GitHub looks for a template in three locations (any one works; pick one):

  • .github/pull_request_template.md ← most common

  • docs/pull_request_template.md

  • pull_request_template.md at the repo root

A minimal template

.github/pull_request_template.md

MD
## Summary

<!-- One or two sentences. What does this PR do? -->

## Why

<!-- Link to the issue or describe the motivation. -->

## How to test

<!-- Steps a reviewer can follow to verify the change. -->
A detailed template

A richer template for larger teams

MD
## Summary
<!-- One or two sentences -->

## Type of change
- [ ] Bug fix (non-breaking)
- [ ] New feature (non-breaking)
- [ ] Breaking change
- [ ] Documentation / chore

## Related issues
Closes #

## What changed
<!-- Bullet list of the meaningful changes -->

## Screenshots / recordings
<!-- For UI changes, drop in a screenshot or short Loom -->

## How to test
1.
2.
3.

## Checklist
- [ ] I added tests for the new behaviour
- [ ] I updated the README / docs where relevant
- [ ] I checked that CI passes locally (`npm test && npm run lint`)
- [ ] I considered the rollback story
- [ ] I notified anyone whose code I’m changing

## Risk and rollback
<!-- What could break? How would we roll this back? -->
Multiple templates

Create a folder of templates and let contributors choose per PR.

Folder layout

Text
.github/
└── PULL_REQUEST_TEMPLATE/
    ├── feature.md
    ├── bugfix.md
    ├── docs.md
    └── chore.md

Contributors pick a template via URL parameter:

Append ?template=NAME.md to the compare URL

Text
https://github.com/acme-co/widget/compare/main...add-csv-export?template=feature.md
Tip
Wire up a tiny shell script or a `gh` extension to open the right template URL from your branch name. Saves the constant copy-pasting.
What a good template includes

  • Summary — one paragraph headline.

  • Motivation / linked issues — closes #N, fixes #M.

  • Type of change — checkboxes help triage and changelog generation.

  • Testing instructions — explicit steps the reviewer can follow.

  • Screenshots — required for UI work; reviewers will fill it in anyway.

  • Checklist — “I added tests / docs / changelog entry”.

  • Rollback — what to do if this breaks in prod.

Issue templates

GitHub has a parallel system for issue templates (bug reports, feature requests, questions). They live in .github/ISSUE_TEMPLATE/ and are covered in detail on the Issue Templates page.

GitLab equivalent

GitLab calls them Merge Request templates, stored in .gitlab/merge_request_templates/. The mechanics are identical — markdown files that pre-fill the description.

GitLab MR template layout

Text
.gitlab/
└── merge_request_templates/
    ├── feature.md
    ├── bugfix.md
    └── Default.md     ← used when nothing is selected
Common pitfalls

  • Template too long — people skip sections. Aim for fewer than 10 bullets.

  • Vague headings — "Description" tells the author nothing. "How to test" gets actual instructions.

  • Mandatory fields nobody fills in — markdown can’t enforce. Use Issue Forms (YAML) if you need required fields.

  • Template lives only on one fork — must be in the upstream repo for PRs from forks to see it.

Real-world workflow

Add a template to a repo

Bash
mkdir -p .github
$EDITOR .github/pull_request_template.md
git add .github/pull_request_template.md
git commit -m "Add PR template"
git push

# Next PR will auto-populate with the template
Templates are a nudge, not a contract
Templates don’t enforce anything — they just lower the cognitive cost of writing a good PR description. The first time you see a five-line template fill in the right information for free, you’ll understand why every mature repo has one.
Tip
Put your most important field — usually **How to test** — near the top. The bottom half of the description gets edited least. Position your asks where attention lives.