Comprehensive Checklist: GitHub PR Template

Greg Foster
Greg Foster
Graphite software engineer

Creating a pull request (PR) template on GitHub can greatly enhance the development process, ensuring consistent communication and efficient reviews. With the right PR template, software engineers can streamline contributions, saving time and reducing errors. In this guide, we decode the benefits of GitHub PR templates, explain how to create them, share best practices, pinpoint common mistakes, offer effective examples from successful open-source projects, and walk through automation and customization techniques.

A well-crafted GitHub PR template brings a multitude of advantages to the development workflow:

  • Consistency: PR templates establish a standard for all contributions, making it easier to review and understand pull requests.

  • Clarity: Templates prompt contributors to include all necessary information, which clarifies the purpose and context of the PR.

  • Quality Control: Incorporating checklists and guidelines can improve the overall quality of the code and documentation.

  • Efficiency: Structured information allows members to spend less time deciphering PRs and more time evaluating the changes put forth.

To create a PR template, simply add a file titled 'PULL_REQUEST_TEMPLATE.md' to your repository's `.github/` folder. (Unfortunately, you can only have one per repository for now.) GitHub will then automatically pre-populate new PRs with the contents of this markdown file. This file should include headings and sections relevant to your project's needs.

Aligning with best practices ensures your GitHub PR template is efficient and functional:

  1. Keep It Simple: Avoid overcomplicating the template. Only include sections that are truly necessary for your team to assess the PR.

  2. Be Specific: Tailor prompts and checklists to your project's requirements to avoid generic or irrelevant information.

  3. Guide the User: Use comments to provide instructions or examples for contributors without cluttering the visible PR description.

  4. Ensure Scalability: As your project grows, so too may your template. Regularly review and adjust it to fit the evolving needs of the project.

Beware of several pitfalls when implementing PR templates such as:

  • Overloading with Information: Too many details can overwhelm contributors. Strive for balance in providing guidance.

  • Being Too Vague: Conversely, being too generic can lead to submissions lacking vital information or context.

  • Resistance to Change: Flexibility is crucial. Don't adhere to a template that isn't working well just because it's been the standard.

Creating effective pull request (PR) templates is crucial for streamlining the development process, enhancing communication, and ensuring consistent code quality across projects. Here are three distinct PR template examples tailored for different scenarios. Each template serves a unique purpose, catering to various project needs—from feature additions and bug fixes to documentation updates.

This template is designed for introducing new features. It ensures that all relevant information about the new functionality is communicated clearly.

Terminal
# Feature Addition PR Template
## Summary
Briefly describe the feature being introduced.
## Rationale
Explain the reasoning behind this feature and its benefits to the project.
## Design Documentation
Link to any design documents or diagrams relevant to this feature.
## Changes
List the major changes made in this pull request.
## Impact
Discuss any potential impacts this feature may have on existing functionalities.
## Testing
Describe how the feature has been tested, including both automated and manual testing strategies.
## Screenshots/Video
Include screenshots or video demonstrating the new feature, if applicable.
## Checklist
- [ ] Code follows the project's coding standards
- [ ] Unit tests covering the new feature have been added
- [ ] All existing tests pass
- [ ] The documentation has been updated to reflect the new feature
## Additional Notes
Any additional information or context relevant to this PR.

This template is optimized for contributions that address and resolve bugs. It focuses on understanding the bug, the fix, and the testing done to ensure the issue is resolved.

Terminal
# Bug Fix PR Template
## Summary
Provide a concise description of the bug and the fix.
## Issue Link
Link to the issue being addressed.
## Root Cause Analysis
Detail the root cause of the bug and how it was identified.
## Changes
Outline the changes made to fix the bug.
## Impact
Describe any implications this fix may have on other parts of the application.
## Testing Strategy
Explain how the fix has been tested to ensure the bug is resolved without introducing new issues.
## Regression Risk
Assess the risk of regression caused by this fix and steps taken to mitigate it.
## Checklist
- [ ] The fix has been locally tested
- [ ] New unit tests have been added to prevent future regressions
- [ ] The documentation has been updated if necessary
## Additional Notes
Any further information needed to understand the fix or its impact.

This template focuses on updates to documentation, ensuring clarity, completeness, and accessibility of information provided to developers and users.

Terminal
# Documentation Update PR Template
## Summary
Brief description of the documentation update and its purpose.
## Areas Affected
List the sections or pages of the documentation that are updated.
## Details
Provide detailed information about the changes made to the documentation.
## Motivation
Explain why these documentation changes are necessary.
## Review Checklist
- [ ] Spelling and grammar are correct
- [ ] All links are working and correct
- [ ] Documentation accurately reflects the current state of the project
- [ ] Changes are clearly highlighted and easy to understand
## Screenshots
Include before and after screenshots for significant visual changes, if applicable.
## Additional Notes
Any other information that might be helpful for reviewers.

Each of these templates serves a different case:

1. **Feature Addition PR Template:** Useful for introducing new features or enhancements. It focuses on the rationale, impact, and testing of the new feature.

2. **Bug Fix PR Template:** Best suited for contributions that address specific bugs. It emphasizes understanding the bug, detailing the fix, and outlining the testing strategy.

3. **Documentation Update PR Template:** Ideal for updates or corrections to the project's documentation. It ensures that documentation changes are thorough, well-explained, and easy to navigate.

By adapting these templates to your project's specific needs, you can improve the PR review process, encourage thorough documentation, and maintain high-quality contributions across your project.

When it comes to streamlining the pull request process, dynamic variables within PR templates could elevate them to new heights of efficiency. Unfortunately, GitHub's current feature set does not support the inclusion of dynamic variables in templates, a gap in functionality that teams might find restricting. While static content remains the standard for PR templates, the integration of evolving content that adapts to the specific context of a pull request would be a significant improvement.

Although GitHub Actions present a promising avenue for automation and customization within the GitHub workflow, there isn't a widely recognized action available at this moment that fulfills the role of injecting dynamic content into PR templates. However, this challenge serves as an impetus for innovation. Teams with precise needs or unique workflows are advised to consider developing a custom GitHub Action. By doing so, they can script customized solutions that introduce dynamic variables into their PR templates, presenting a tailored approach that aligns with their project's demands. This advanced application of GitHub Actions would not only cater to specific use cases but also place the team at the forefront of repository management efficiency.

Using GitHub Actions to enforce PR template compliance is a powerful strategy to automate and uphold your project's contribution standards. By ensuring that all pull requests adhere to your template, you maintain consistency and quality across contributions. The custom GitHub Action example provided below illustrates how to automate the validation of PR descriptions against your project's PR template.

This section outlines how to use GitHub Actions to ensure contributors fill out the PR template properly. The goal is to automate the verification process, making sure that the PR descriptions match the expectations set by the template, rather than leaving the descriptions empty or as unfilled templates.

The provided GitHub Action script automatically checks if the PR description sufficiently differs from the PR template, indicating that the author has filled out the template thoughtfully. Here's how it works:

- Trigger: The Action is triggered on PR events such as opened, edited, or synchronized.

- Fetch PR Template: It retrieves the PR template from the repository.

- Compare PR Description and Template: It compares the actual PR description against the fetched template to ensure that the author has replaced template placeholders with relevant information.

The Action outputs whether the PR description deviates adequately from the template, indicating that it has been customized by the author. If the description is too similar to the template (suggesting it wasn't filled out), the Action will fail, prompting the author to provide more detailed information.

Terminal
name: Validate PR metadata
on:
pull_request:
types:
- opened
- edited
- synchronize
jobs:
validate-description:
name: Validate description
runs-on: ubuntu-latest
steps:
- name: Fetch PR Template
run: |
curl -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" -s "https://raw.githubusercontent.com/$GITHUB_REPOSITORY/main/.github/PULL_REQUEST_TEMPLATE.md" -o pr_template.txt
- name: Compare PR Description and Template
run: |
jq --raw-output ".pull_request.body" "$GITHUB_EVENT_PATH" > pr_body.txt
echo "PR template:"
echo "--------------------------"
cat pr_template.txt
echo
echo "PR body:"
echo "--------------------------"
cat pr_body.txt
echo
echo "========================================================"
echo
DIFF_COUNT=$(diff -y --suppress-common-lines pr_body.txt pr_template.txt | wc -m)
echo "The PR description is $DIFF_COUNT characters different from the template."
if [ "$DIFF_COUNT" -lt 20 ]; then
echo "PR description is too similar to the template."
exit 1
else
echo "PR description is sufficiently different from the template."
fi

1. Copy the Action Script: Copy the provided YAML script into a new file in your repository under .github/workflows/, for example, validate_pr_description.yml.

2. Customize as Needed: You may adjust the DIFF_COUNT threshold based on your needs. A lower DIFF_COUNT means stricter enforcement, requiring more significant differences between the PR description and the template.

3. Commit and Enable: Commit the new workflow to your main branch. GitHub will automatically start running this action on subsequent PRs based on the triggers defined.

This custom GitHub Action helps ensure that contributors are actively filling out the PR template, leading to more informative and valuable pull requests, which in turn facilitates better code reviews and project maintenance.

By harnessing the power of GitHub PR templates, software engineer teams can drastically improve productivity and code quality. Moving beyond static checklists, the modern evolution of these templates involves dynamic content and automation, providing a platform for growth and adaptation.

Graphite
Git stacked on GitHub

Stacked pull requests are easier to read, easier to write, and easier to manage.
Teams that stack ship better software, faster.

Or install our CLI.
Product Screenshot 1
Product Screenshot 2