Github Templates: The Smarter Way to Formalize PRs Among Dev Teams

Introduction

Today I’m going to give you a better, easier, more efficient way to keep pull requests not only uniform but also completely customized to your dev team.

Some common issues of a dev team

If you’ve ever worked with GitHub as a software developer, either solo or as part of a team, you should be familiar with the issues I’m about to show you.

Leaving less than stellar commit messages

First, the nonsensical commit messages. These are usually sent multiple times because we, as developers, are lazy and will keep pushing changes to GitHub with the same note even though the code update has nothing whatsoever to do with that message.

NOTE:: If you want to see some laugh out loud commit messages, I highly recommend the website What the Commit. Just keep refreshing the page for a constant stream of hilarious (and accurate) commit messages.

Completely puzzling pull requests

You’ve seen (and/or submitted) a pull request like this one to a repo — don’t try to deny it. Names and discerning details have been omitted to protect the privacy of the guilty.

Yes, this is an actual pull request on GitHub, titled only as “catching up” with a ton of commit messages that give very little context and no other details to anyone reviewing this any idea as to what was going on here.

At this point, you may be thinking to yourself that this does, in fact, resemble things you’ve seen (or submitted) before and you might not see a huge problem with it.

If you’re a solo developer working on your own projects, always aware of everything in the code base, I might be inclined to agree with you. However, if you’re on a team with 10 or 20 other developers and building an application used by hundreds or thousands of people, where other developers have to look at the changes you made, determine if the code and logic is sound and it won’t break anything in your main code branch, this is a big, big problem.

Temporary solutions - don't both using these options ⚠️

To solve these problems there are a few different solutions that my development team tried in the past:

Option 1: A completely manual process

A loose collection of requirements we had to manually add to every new pull request. Things like:

• Links to the feature story we were working on in our backlog,
• Links to the automated Jenkins branch where our feature branch was built and deployed into QA,
• Links to the feature branch for testing,
• A code coverage report,
• Links to related PRs in other repos, etc.

This worked OK, except people commonly forgot (or just didn’t care to add) one or more of these links, and we didn’t have a formalized system for new devs joining the team to know how to format their PRs.

Option 2: A template that needed to be copy/pasted into every PR, every time

Our second attempt was slightly less manual: A pull request template that my team kept in a Slack .txt file pinned in one of our development channels. Here’s what that looked like:

## Story
Jira, Pivotal Tracker, (link to where the story you worked on lives)

## PR Branch
URL to the automated branch build for feature testing

## Code Coverage
URL to the automated code coverage report run during the automated build process

## e2e
URL to the automated end to end tests run against the feature branch

## UX Approved
yes / no

## Newman
yes / no

## Related PR's
TBD

But once again, devs had to go find the template, copy the markdown formatting, and paste it into each and every pull request opened up and fill out the contents of it.

This worked better because the template, at least, ensured there was less chance of forgetting something, but it still wasn’t foolproof. Oftentimes (because devs are people and people are lazy, myself included), we’d just go find an old closed PR, copy its contents and paste it into the new PR we were working on. That was OK until someone forgot to update the story link or the end to end test link... you see the issue.

But that was the best solution anyone had until our team had some fresh developers brought on board.

As I was showing one of our new devs the PR template we used (by copying it from out of another closed pull request), he asked why we didn’t just use GitHub Templates, and I said, “because none of us had ever heard of them.” Then, he showed me something really cool and very easy to do.

A better solution - what we're using now (and you should too) ⭐️

Option 3: GitHub Templates - the automated way to do PRs

GitHub templates are an awesome invention from GitHub for both pull requests and issues. Since PRs are what concerned my team, I found the GitHub docs to learn more.

Here's what I learned from the docs:

"When you add a pull request template to your repository, project contributors will automatically see the template’s contents in the pull request body." — GitHub Docs

This was just the sort of thing my team needed. It was a way to ensure every pull request was uniform without our devs having to think about it. Perfect.

Turns out, it was incredibly easy to set up as well.

Setting up GitHub Templates in a project

Although setting up a PR template is very straightforward, I’m happy to lay out the steps here for convenience sake.

Step 1: Add a .github/ folder into the root of your project

The docs say you can either add the PR template in the root directory itself or in a folder named docs/ or .github/.

Since we wanted to ignore the PR folder the majority of the time we were doing development, I chose to create the template inside of the hidden .github/ folder.

Step 2: Add your pull_request_template.md markdown file inside the folder

In order for Github to automatically pick up the formatting from the markdown file for PR templates, you must name the file pull_request_template.md.

Below is an example of the one my team uses:

# <Feature Title>

Tracker ID: **_#ADD LINK TO PIVOTAL STORY_**

Unit tests completed?: (Y/N)

PR Branch
**_#ADD LINK TO PR BRANCH_**

Code Coverage & Build Info
**_#ADD LINK TO JENKINS CONSOLE_**

E2E Approved
**_#ADD LINK TO PASSING E2E TESTS_**

Windows Testing
**_#HAS WINDOWS BEEN TESTED?_**

Related PR
**_#ADD ANY RELATED PULL REQUESTS_**

UX Approved
**_#ADD UX APPROVAL IF NEEDED_**

Step 3: Add these files to your main branch and prepare for smooth sailing in all PRs going forward

Here’s a screenshot of a repo I have with the pull request template added to it, and an example pull request I raised.

It really is that simple to have a standardized PR template included in any repo with very little effort.

Conclusion

When you’re working with a team of developers on a mission-critical product, pull requests are a necessary evil, but they can be less painful with the help of GitHub’s pull_request_templates.

The benefits of the formatted PR templates are many, but some of the highlights in my mind are how flexible they are; no matter what your team deems necessary to review and accept, a pull request can be easily included and implemented in any repo. That’s the kind of ease developers need for required formalities like PRs.

Check back in a few weeks, I’ll be writing about JavaScript, ES6 or something else related to web development.

Thanks for reading, I hope this helps you better manage your own team’s pull requests in an easy and more orderly fashion.

References & Further Resources

• Example original, manual Pull Request Template gist
• Pull Request Template in repo
• Example new, automated Pull Request Template gist
• Github Templates docs