Github Templates: The Smarter Way to Formalize Pull Requests Among Development Teams
No more confusing pull requests
Welcome! 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.
The Common Issues
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 update has nothing whatsoever to do with that message.
Side 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
master code branch, this is a big, big problem.
Temporary Solutions — Don’t Bother 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 the 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:
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
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
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
Below is an example of the one my team uses:
Step 3: Add these files into your
master branch and prepare for smooth sailing in all pull requests 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.
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
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.
Thanks for reading, I hope this helps you better manage your own team’s pull requests in an easy and more orderly fashion. Please share this with your friends if you found it helpful!
References and further resources:
- Example Original, Manual Pull Request Template gist: https://gist.github.com/paigen11/0df23cdf168057dd5e8cf3c61d5beb0f
- Pull Request Template in Repo: https://github.com/paigen11/mysql-registration-passport
- Example New, Automated Pull Request Template gist: https://gist.github.com/paigen11/9ef7fd2b08de2b8a9976615c633ada02
- Github Templates docs: https://help.github.com/en/articles/creating-a-pull-request-template-for-your-repository