GitHub pull request template

Welcome to this guide on GitHub pull request templates! We hope you'll find what you are looking for, and if you're interested in the best way to manage your pull requests in Slack, you should take a look at Axolo, which helps thousands of developers merge pull requests faster (also incubated by Slack in 2023). Also if you are interested we wrote a piece on why your pull requests are taking forever, learn more about the GitHub pull request workflow here.

Why should you use a pull request template

A GitHub pull request template allows your organization to have a standardized and repeatable default text whenever you create a new pull request. This ensures that every PR has a clear, consistent structure. By providing a predefined checklist, guidelines, and prompts, you’ll see benefits such as:

• Ensuring contributors follow a uniform review process.
• Reducing back-and-forth communication by clarifying expectations upfront.
• Saving time by not having to rewrite the same instructions for each PR.
• Improving overall code quality and maintainability.

As you scale your development team, having a structured approach is essential. Standardization helps prevent confusion and miscommunication. It also ties into the concept of what is a pull request, making sure that everyone on the team understands the expectations and the steps needed before requesting a review.

To implement a GitHub pull request template, simply add a file called PULL_REQUEST_TEMPLATE.md to your repository’s root or .github/ directory. The template can include checklists, a summary section, testing guidelines, or references to relevant issues. If you’re using GitHub multiple pr templates, you can differentiate them by placing them in the .github/PULL_REQUEST_TEMPLATE/ folder and selecting the appropriate one when opening a PR.

Also, consider the relationship between pull requests and merge requests. Learn more by checking out the pull request vs merge request comparison to understand best practices across different platforms.

Key Components of a Good Pull Request Template

A strong pr template should set clear expectations and facilitate a smooth review process. When you build a GitHubtemplate, think about including the following elements:

Clear Title and Description

Your template should prompt the contributor to provide a brief, yet informative, title and a summary describing the purpose of the PR. This helps reviewers quickly understand the context and goals.

Reference to Related Issues or Tasks

Linking relevant issues or tasks ensures that everyone understands why this PR exists. When you’re using GitHub project templates, referencing related issues streamlines project tracking.

Checklist of Requirements

A well-defined checklist of prerequisites helps authors verify they haven’t missed critical steps. For instance, confirm that tests pass, code is documented, or certain conditions are met. Including these can reduce the number of review cycles.

Instructions for Testing

Encourage contributors to detail how reviewers can test the changes. This could include information on setup steps, test commands, or even user flows to follow. Having a consistent testing approach keeps quality high.

Additional Context or Screenshots

Sometimes, a PR is more understandable with added context. Encouraging screenshots, logs, or links to documentation can speed up understanding, especially when onboarding new contributors.

The above components serve as a general blueprint. For an actual pull request template example, keep reading as we’ll delve into various templates shortly.

How to Create a GitHub Pull Request Template

Creating a GitHub pull request template involves just a few steps. Before you start, consider leveraging a GitHub template repository or GitHub repository template. These resources help you jumpstart your standardization process. You can also explore GitHub create template repository functionalities to streamline your onboarding process.

Step 1: Add Your Template File

Create a file named PULL_REQUEST_TEMPLATE.md at the root of your repository or within a .github/ folder. If you’re working with a GitHub template repository, start from a template that already includes a PR file. For those who maintain large projects, consider making use of GitHub multiple pr templates to handle different use cases (e.g., bug fixes vs. feature additions).

Example directory structure:

.
└── .github/
    ├── PULL_REQUEST_TEMPLATE/
    │   ├── bug_fix_template.md
    │   ├── feature_template.md
    └── PULL_REQUEST_TEMPLATE.md

Step 2: Customize the Template Content

Inside PULL_REQUEST_TEMPLATE.md, draft your pr template content. Include headings, checklists, and references to related issues. For inspiration, refer to a pull request template example from this article or from public repositories. Adjust it to your team’s needs, ensuring you’re consistently referencing GitHub issue template usage and processes as needed.

Step 3: Commit and Push

Once you’ve finalized the template, commit and push it. From that point forward, every new pull request will automatically load the default content from your pr template. If you’re using GitHub multiple pr templates, GitHub will prompt you to choose the appropriate one, ensuring you always start from the correct baseline.

Check out how others incorporate templates by examining GitHub bug report template or GitHubcreate template repository documentation. These resources can help you standardize more than just pull requests – they help you streamline issues, features, and more.

Step 4: Iterate and Improve

Your first version of the template might not be perfect. Over time, refine your GitHub template by adding new requirements, clarifying instructions, or simplifying steps. Continuous improvement ensures that your team always benefits from the best possible process.

7 GitHub pull request template examples

Below, there are 6 pull request templates we recommend you to test. You can also find them on our pull request template repository ready to be copied.

Find more on SteveLao GitHub issue templates and Awesome GitHub templates

Example 1: Simple pull request template with a checklist

## Describe your changes

## Issue ticket number and link

## Checklist before requesting a review
- [ ] I have performed a self-review of my code
- [ ] If it is a core feature, I have added thorough tests.
- [ ] Do we need to implement analytics?
- [ ] Will this be part of a product update? If yes, please write one phrase about this update.

Example 2: Detailed description pull request template

# Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context. List any dependencies that are required for this change.

Fixes # (issue)

## Type of change

Please delete options that are not relevant.

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] This change requires a documentation update

# How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration

- [ ] Test A
- [ ] Test B

**Test Configuration**:
* Firmware version:
* Hardware:
* Toolchain:
* SDK:

# Checklist:

- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged and published in downstream modules

Example 3: Pull request template for external contributions with related issues

THIS PROJECT IS IN MAINTENANCE MODE. We accept pull requests for Bug Fixes **ONLY**. NO NEW FEATURES ACCEPTED!

<!--- Provide a general summary of your changes in the Title above -->

## Description
<!--- Describe your changes in detail -->

## Related Issue
<!--- This project only accepts pull requests related to open issues -->
<!--- If suggesting a new feature or change, please discuss it in an issue first -->
<!--- If fixing a bug, there should be an issue describing it with steps to reproduce -->
<!--- Please link to the issue here: -->

## Motivation and Context
<!--- Why is this change required? What problem does it solve? -->
<!--- If it fixes an open issue, please link to the issue here. -->

## How Has This Been Tested?
<!--- Please describe in detail how you tested your changes. -->
<!--- Include details of your testing environment, and the tests you ran to -->
<!--- see how your change affects other areas of the code, etc. -->

## Screenshots (if appropriate):

Example 4: Checklist for open-source pull request template

 All Submissions:

* [ ] Have you followed the guidelines in our Contributing document?
* [ ] Have you checked to ensure there aren't other open [Pull Requests](../../../pulls) for the same update/change?

<!-- You can erase any parts of this template not applicable to your Pull Request. -->

### New Feature Submissions:

1. [ ] Does your submission pass tests?
2. [ ] Have you lint your code locally before submission?

### Changes to Core Features:

* [ ] Have you added an explanation of what your changes do and why you'd like us to include them?
* [ ] Have you written new tests for your core changes, as applicable?
* [ ] Have you successfully run tests with your changes locally?

Example 5: Checklist and detailed description GitHub pull request template

* **Please check if the PR fulfills these requirements**
- [ ] The commit message follows our guidelines
- [ ] Tests for the changes have been added (for bug fixes/features)
- [ ] Docs have been added / updated (for bug fixes / features)


* **What kind of change does this PR introduce?** (Bug fix, feature, docs update, ...)


* **What is the current behavior?** (You can also link to an open issue here)


* **What is the new behavior (if this is a feature change)?**


* **Does this PR introduce a breaking change?** (What changes might users need to make in their application due to this PR?)


* **Other information**:

Example 6: Open-source to-do list pull request template for GitHub

## Pull Request template
Please, go through these steps before you submit a PR.

1. Make sure that your PR is not a duplicate.
2. If not, then make sure that:

    a. You have done your changes in a separate branch. Branches MUST have descriptive names that start with either the `fix/` or `feature/` prefixes. Good examples are: `fix/signin-issue` or `feature/issue-templates`.

    b. You have a descriptive commit message with a short title (first line).

    c. You have only one commit (if not, squash them into one commit).

    d. `npm test` doesn't throw any error. If it does, fix them first and amend your commit (`git commit --amend`).

3. **After** these steps, you're ready to open a pull request.

    a. Your pull request MUST NOT target the `master` branch on this repository. You probably want to target `staging` instead.

    b. Give a descriptive title to your PR.

    c. Describe your changes.

    d. Put `closes #XXXX` in your comment to auto-close the issue that your PR fixes (if such).

IMPORTANT: Please review the [CONTRIBUTING.md](../CONTRIBUTING.md) file for detailed contributing guidelines.

**PLEASE REMOVE THIS TEMPLATE BEFORE SUBMITTING**

We hope you've found your perfect pull request template! Keep on reading and discover our next pull request dive in: Part IV: How to review code in GitHub

Common Mistakes to Avoid

When implementing a GitHub pull request template, watch out for:

1. Overly Complex Templates:
   If the template is too long, contributors may ignore it. Keep instructions concise and meaningful.

2. Generic Prompts Without Context:
   Avoid vague instructions. Instead of “Run tests,” specify which tests or what environment to test in.

3. Forgetting to Update Templates Regularly:
   Projects evolve. Regularly revisit your templates to ensure they still align with best practices and GitHub code review best practices.

4. Not Leveraging GitHub’s Features:
   Don’t forget you can combine templates with automated workflows. For instance, use GitHub actions on pull request triggers to run tests, linting, or security scans automatically.

5. Ignoring Multiple Templates for Different Use Cases:
   Sometimes, a single template doesn’t fit all scenarios. Consider using GitHub multiple pr templates to handle bug fixes, new features, and documentation updates differently. Each scenario can have its own pull request template example, ensuring maximum relevance.

Integrating PR Templates into Your Workflow

A PR template is only one piece of the puzzle. Consider integrating it with other parts of your development lifecycle:

• Project Onboarding:
  When setting up a new project, consider using GitHub create template repository steps to generate a standardized project framework. This helps new repos start with the right structure, including PR and issue templates.

• Code Review and Communication:
  Encourage the team to use the template consistently. Mention the importance of these templates during onboarding and team syncs. Enhanced consistency leads to faster, more efficient reviews. For more advanced review strategies, explore code review best practices.

• Linking to Documentation:
  Within the PR template, link to documentation on coding standards, architectural decisions, or testing guidelines. This empowers contributors to find information quickly.

• Tie into Existing CI/CD:
  Combine your PR template with GitHub actions on pull request events. Trigger automatic builds, tests, or security checks as soon as a PR is opened, ensuring faster feedback loops.

By integrating PR templates into all aspects of your workflow, you ensure everyone is aligned, resulting in better collaboration and code quality.

Bonus: Issue templates for your project

Just as PR templates bring consistency to pull requests, a GitHub issue template ensures that anyone reporting a bug or requesting a feature follows a standardized format. Issue templates can guide users and contributors to provide the right details, reducing the time it takes to understand and address problems.

If you’re scaling up your templates strategy, consider creating a GitHub template directory that contains both issue and PR templates. You can also check out feature request template references at feature request template to standardize feature requests as well. Similarly, adopting a GitHubbug report template helps streamline how users and contributors raise issues, ensuring enough detail is provided from the start.

Bonus: Issue templates for your project

And if you're working with open-source projects, you might need the help of some useful issue templates in your repositories. Recently, GitHub developed multiple issue templates. For example, GitHub users looking to post an issue will face something like this (React example):

Example 1: Simple GitHub issue template

## Expected Behavior


## Current Behavior


## Possible Solution


## How to reproduce (for bugs)

Example 2: Detailed GitHub issue template

## I'm submitting a ...

- [ ] bug report
- [ ] feature request

## What is the current behavior?

## If the current behavior is a bug, please provide the steps to reproduce and if possible a minimal demo of the problem

## What is the expected behavior?

## What is the motivation / use case for changing the behavior?

## Please tell us about your environment:

Version: 2.0.0-beta.X
Browser:
Language:

Maximize the Potential of GitHub PRs with Axolo

While templates provide structure and reduce friction, you can take your workflow to the next level with the right tools. Axolo offers a Slack integration that brings all the benefits of a GitHub pull request template directly into your team’s communication hub.

• Real-time Notifications:
  Receive updates on new PRs, comments, and approvals directly in Slack, ensuring no change slips through the cracks.

• Faster Code Reviews:
  Axolo helps teams quickly converge in a temporary Slack channel dedicated to a specific PR, speeding up the entire feedback process.

• Better Context Sharing:
  Share links to documentation, reference PR templates, and provide clarifications without leaving Slack. For more best practices, dive deeper into GitHub draft pr or learn how to optimize your review process with GitHub code review best practices.

By integrating Axolo, your templates and workflows meet seamless communication. This results in higher velocity, reduced confusion, and a well-orchestrated development cycle.

By now, you should have a solid understanding of how to implement, improve, and leverage GitHub pull request template strategies. From understanding the key components and exploring pull request template example formats to integrating them into your workflow, you have all the tools you need. Don’t forget the value of a GitHub issue template and GitHub bug report template in maintaining top-notch quality across your entire repository.

Whether you are starting a new project with a GitHub create template repository approach, or refining an existing one, these templates will save time, ensure consistency, and help maintain a high standard of quality. And if you’re looking for even more efficiency, consider combining your PR templates with Axolo’s Slack integration for a truly seamless experience.

Now that you’ve got all this insight, why not take a step further and explore how to refine your GitHub template approach or experiment with GitHubmultiple pr templates to handle various scenarios? The possibilities are endless, and the benefits are clear.

Ready to dive even deeper into best practices for reviews and beyond? Check out the next part of our series: GitHub code review best practices.