What’s going on all you amazing devs out there in the web world? I hope you had a chance to check out the series on using git and GitHub. By now you should have a good understanding of some introductory Linux commands, git commands, the GitHub user interface, and the GitHub flow. In this article we are going to walk through crafting a pull request (PR) template for your organization’s project to keep things on track and organized. PR templates are such a great thing to have in your project. I recommend them 100%.
Let’s get started shall we?
Creating Files and Folders
There are two things that need to be created in order for the PR template to work. Yep, only two things! One is a directory, and one is a markdown file. The directory you are going to create will have a period preceding it and it will be visible in GitHub. However, if you were to view it in your file explorer or terminal locally, it will be hidden.
When there is a period (.) before a file or folder that denotes that it is hidden. If you are working in your terminal and want to see all files and folders, the command to run would be ls -a. What this command is telling your computer is to list all the files, including hidden ones. The -a indicates “all”.
Go ahead and create a folder called .github and a file named pull_request_template.md.
You are going to create the .github directory at the root of the project. Change directories into that folder and create or touch a pull_request_template.md file. The “md” extension means markdown. This file will be created in markdown.
Template Creation
Now comes the fun part, creating the template. Now, this template can take many forms. I personally like to add as much info in there as possible. Your mileage may vary based on your team’s needs. If your team uses Cypress or Jest, your checkboxes might look different. It all depends on your team’s process for doing checks before submitting the PR.
Start thinking about what your team might want. Have conversations with your team and collaborate with them on what to put in the PR template. This isn’t something you want to do in isolation. Please communicate your actions to your team so they know what you are about to do.
In PR templates I have created, I always had an outline that looks like this below:
- Description with screenshots if needed
- Task URL (Jira, ADO, Asana, etc.)
- Checklist
- Item 1
- Item 2
- Item 3
- How has this been tested?
- Test 1
- Test 2
- Test 3
- Other info
The sub-items will vary. I have specific ones that I include. All of this will be written in markdown and committed to GitHub. Through some magic in GitHub, when you submit a PR, GitHub recognizes that there is a pull request template in the github directory. As a result, you are prompted to fill out the template before you can submit the PR.
Example Template
Feel free to use this and modify as you see fit, some of these options were handpicked from this GitHub pull request template from Axolo. Some of the options were from what I have used in the past. There will be a link to a gist where you can copy and paste the markdown file in your own github folder. You will just have to create the directory and create the file.
Above is what the generated markdown looks like. If you want to use that code, you can get the template by navigating to the pull request template example gist.
Wrapping Up
Using pull request templates in the modern age of the web is such a crucial thing to do for your team. You want to make sure that your team is staying organized and knows what everyone is doing. It is much better to submit a PR with a template of information that was done, than submitting a PR with a sentence description of what was done and calling it a day.
I also wanted to mention that when using a conventional commit style PR title, it is less painful to scan open and closed PR’s in the Pull Request tab on GitHub. You can visually see what is out there, what has been closed, and what may or may not go into a release or build.
You, your future self, and your team will thank you for implementing something that can speed up the process of getting code in quickly and efficiently.
Get Split Certified
Split Arcade includes product explainer videos, clickable product tutorials, manipulatable code examples, and interactive challenges.
Switch It On With Split
Split gives product development teams the confidence to release features that matter faster. It’s the only feature management and experimentation platform that automatically attributes data-driven insight to every feature that’s released—all while enabling astoundingly easy deployment, profound risk reduction, and better visibility across teams. Split offers more than a platform: It offers partnership. By sticking with customers every step of the way, Split illuminates the path toward continuous improvement and timely innovation. Switch on a trial account, schedule a demo, or contact us for further questions.