Jake Worth

• github
• devexp

Have you ever seen a pull request that seems to completely explain itself?

It’s a real artifact. I don’t know the project, yet I understand it. How can we get results like this on every pull request, from every developer on the team, every time?

The answer is a pull request template. Templates give your team a format that’s detailed, discoverable, and predictable. In this post, I’ll share this technique and why it matters.

The Pull Request Template Technique

For Github, create a file in your repo like this:

$ touch .github/pull_request_template.md

The markdown contents of this file will be populated into your Github pull request descriptions.

My Standard Template

Here’s a template I’ve used:

### What

<!-- Replace with your ticketing software URL -->
https://www.pivotaltracker.com/story/show/184285254

<!-- What does this change accomplish? -->

### Why

<!-- Why is it worth doing? -->

### How

<!-- How does it work? -->

<!-- Screenshots -->

Note the comments:

<!-- Replace with your ticketing software URL -->

These will be visible in your pull request text area to prompt you, but not shown to reviewers. Just like a form!

Let’s consider each part of this template:

What: what is the purpose of this change? The goal here is a sentence such as “Allows employees to edit customer emails.” We add a link to our agile ticketing software for even more context.

Why: the question of questions! Why should we merge this? Again, the goal is a sentence like: “Employees need to be able to change customer emails.”

How: here we’re looking for information the code can’t convey, such as remarkable details, edge cases, unfinished work, outstanding questions, etc. Our comment encourages high-bandwidth communication like screenshots or videos.

Why It Matters

If you’re consistently opening pull requests with titles like “fix bug” and no description, you’re making life for your team unnecessarily difficult. Pull requests aren’t just a side effect of the change; they’re an integral part. They should be detailed, discoverable, and predictable. That’s why templates matter.

Pull requests should be detailed– every code change is a risk, so we want each one to be screaming its purpose to the world. This gives everybody, programmers and non-programmers, a chance to understand the value of the change and identify its shortcomings.

Pull request should be discoverable– we want Github’s search to have as many changes as possible to find this change or issue, and that means providing lots of detail.

Finally, pull requests should be predictable– we want reviewers to see the changes first, not your idiosyncratic explanation. A template enforces and predictable, scan-able format.

What are your thoughts on pull request templates? Let me know!