Skip to main content

Dec 15, 2022

Adding a pull request template to your GitHub repo

A blank, white page in a spiral-bound notebook with a sharpened pencil laying on it.
Photo by Kelly Sikkema

If you spend time wondering what to write in the blank “Description” field every time you open a pull request, adding a PR template to your repo will speed you up.

By pre-filling that “Description” field with a few quick prompts to answer, you’ll always know what to write and your reviewers will always get the info they need.

How to add a PR template

  1. Create a folder called .github at the root of your repo
  2. Create a file called .github/pull_request_template.md
  3. Use GitHub’s Markdown syntax to add any prompts you think will be useful to that file

That’s it! Each time you open a pull request, the description section will now be pre-filled with your template.

What to include in your template?

Feel free to add any prompts you like! I prefer to keep it simple:

.github/pull_request_template.md
## ✅ What
 
<!-- A brief description of the changes in this PR. -->
 
## 🤔 Why
 
<!-- A brief description of why we want these changes. -->
 
## 👩‍🔬 How to validate
 
<!-- Step-by-step instructions for how reviewers can verify these changes work as expected. -->
 
## 🔖 Related
 
- [Jira task](url)
- [Slack thread](url)

(Those comments are only visible while editing.)

Don’t overdo it

Whatever you do, don’t make your PR template too long. If you notice your team keeps skipping certain prompts, don’t hesitate to remove them. Only include prompts that actually save everyone time.

If your reviewers always have to ask which ticket each PR relates to, adding a ticket link prompt to the template is probably a good idea. But adding 50 well-intentioned checkboxes will only teach your team to ignore the template entirely.

So, keep it short. 😊

Related