A Pull Request Template for Creating Meaningful PRs
Add this file PULL_REQUEST_TEMPLATE.md to the root directory of your repository.
Check out the Pull-Request-Template Lunch and Learn presented at The Frontstide
Describe the Purpose
of the pull request. Include background information if necessary
A PULL_REQUEST_TEMPLATE helps to standardize the important information in a Pull Request. Software is hard and appications are large, so no matter how self-documenting the code is today, we need to provide a healthy environment for discussion tomorrow.
Writing a Pull Request can feel like a hurdle that stands between the developer and shipping code. This leads to some common issues with Pull Requests:
This Pull Request . . .
- has no description
- does not solve the problem
- just wordsplains the code
- is way over my head
The Approach
section details 'HOW does this change fulfill the purpose?'
This PULL_REQUEST_TEMPLATE.md adds structure to our PRs in order to solve some common issues
This Pull Request has no description
- Write
Write a Description
Section 😖
This Pull Request does not solve the problem
- Write
Research the Problem
Section
This Pull Request just wordsplains the code
- Write
Let the Code Tell Us About the Code
Section
This Pull Request is way over my head
- Write
Share the Knowlege
Section
Just a reminder, writing a Pull Request, like code, is a process. It requites more than one iteration to get it right.
The Learning
section explains 'WHAT I learned in boating school today is ...'
Approach each PR as a docuement for sharing knowledge. When we teach the assignee/reviewer through a Pull Request, we build confidence that the developer has taken due dilligence during the research phase.
The assignee is not treated as a Merge Button Gatekeeper, but a collaborator. Awell written PR invites everyone to learn and and be part of the process of shipping code.
- Thanks to Github Templates for making this possible
- More fine-grained reading on Writing the Perfect Pull Request