Pull requests are the standard way to request a change to be merged into the main or stable branch. Having fellow developers or maintainers review the change is crucial to ensure its quality, although exceptions may apply for teams using pair programming or mob programming approaches. Since changes shouldn't disrupt the existing working software, having an effective review process is vital.
During the review, reviewers need clear context about the changes being reviewed. Unclear information can lead to back-and-forth discussions, causing delays and unnecessary context switching, ultimately impacting team velocity.
To ensure that contributors provide sufficient information about the changes to be reviewed, it's ideal to use a standard pull request template that prompts them for the necessary details.
Both GitHub and GitLab supports pull request templates. The details can be found at the following links respectively:
Based on what suits your team needs and technology, various check lists and contextual questions can be added to the PR templates for the contributor.
Here is one such sample of the PR template:
<! -- Remove sections that are not relevant to PR -->
## 🎯 Description, Motivation and Context
## 🔗 Link to the resources (design, issue/feature ticket)
## ✅ How has this been tested?
## 📷/🎥 Screenshots:
## ☑️ Checklist:
You have to check all boxes before merging
[ ] Updated the PR name to follow our PR naming guidelines
[ ] Wrote unit tests and/or ensured the tests suite is passing
[ ] Checked linter on local.
[ ] If needed I updated documentation.
When working on UI:
[ ] I checked and implemented accessibility (minimum Dynamic Text and VoiceOver)
[ ] I verified the UI on smaller devices
[ ] I verified the UI on devices with notch
[ ] I verified the UI on orientation changes
## 🚉 Which modules have been affected?
<! -- In case of Monorepo -->
[ ] Core
[ ] UIKit
[ ] Module 1
[ ] Module 2
[ ] CI configuration
## 🧐 Any special note?
The team can continually adjust this template to fit their needs better. They can remove sections that aren't very helpful and add sections that focus on the details important for the review.
There are various benefits of using a pull request template:
Standardisation: Pull request templates provide a standardised format for creating pull requests. This consistency ensures that essential information, such as the purpose of the changes, related issues, testing steps, and any necessary context, is included with each pull request. Standardization reduces confusion and ensures that contributors provide the necessary details for efficient code review.
Clarity and Context: It helps reviewers understand the changes being proposed and provides them with the necessary context to provide valuable feedback.
Efficiency: Templates prompts the contributors to provide essential information upfront. This reduces the back-and-forth communication between contributors and reviewers and speeds up the review process.
Saves CI Cost: Many teams use CI integration, which kicks off when a pull request is created. This ensures that all workflow steps pass, such as lint checks and running test suites. If, for example, a lint check fails, it wastes CI credits/build time and adds unnecessary costs to the company. A checklist for contributors ensures they validate all necessary steps before creating pull requests, preventing oversights.
Here are few more resources for the templates:
https://github.com/devspace/awesome-github-templates?tab=readme-ov-file
https://github.com/TalAter/open-source-templates?tab=readme-ov-file
https://github.com/stevemao/github-issue-templates
Let me know if you found this helpful. Feel free to tweet me on Twitter if you have any additional tips or feedback.
Thanks