Why Great PRs Are Great: Pull Requests Templates

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:

$ t o u c h . g i t h u b / p u l l _ r e q u e s t _ t e m p l a t e . m d

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 (now in a Gist):

### What

<!-- Link to site where you track your work -->
[Ticket](https://www.pvtltrckr.com/story/show/180285254)

<!-- What does this change accomplish? Example: "Adds a log-in feature." -->

### Why

<!-- Why is it worth doing? Example: "Lets users access their account." -->

### How

<!-- How does it work? Remarkable details, questions, edge cases, unfinished work, etc. -->

<!-- Screenshots, videos, GIFs, links, etc. -->

Note the comments:

<!-- Link to site where you track your work -->

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! What’s the why? 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 introduces some 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 its value and see its shortcomings.

Pull request should be discoverable. We want Github’s search to have as many chances as possible to find this change, and that means providing lots of detail.

Finally, pull requests should be predictable. We want reviewers to see the changes, not your idiosyncratic explanation. A template enforces a predictable, parseable format.