GitHub pull request templates

This guide will walk you through how to create, add, and manage pull request templates in your GitHub repositories. We'll also discuss how to handle multiple templates at a time and set a default template.

What is a GitHub pull request template?

A GitHub pull request template is a markdown file that GitHub uses to pre-populate the body of a new pull request. The template can include anything from a checklist, instructions, reminders to specify specific information about the code, or links to relevant resources or policies.

Benefits of using pull request templates

• Consistency: Ensures that all pull requests contain the necessary information needed for the reviewer, which can include testing steps, screenshots of changes, specific areas of concern, etc.
• Efficiency: Reduces the time spent on writing and reviewing pull requests by outlining what needs to be included.
• Quality control: Helps maintain a high standard of code review by reminding contributors of requirements and guidelines.

Step 1: Create a pull request template

Single pull request template

1. Navigate to your repository: Open your repository on GitHub.
2. Create the template: Inside the .github folder, create a file named PULL_REQUEST_TEMPLATE.md.
3. Add content to the template: Edit the file to include the sections and information you want contributors to include in their pull requests.

Example of a simple pull request template:

## Description

Describe the purpose of this pull request.

## Changes

List the changes you have made.

## Additional Information

Include any additional information, such as how to test your changes.

## Checklist

- [ ] Tests passed
- [ ] Documentation updated

Multiple pull request templates

If your project requires different types of pull requests, you can create multiple templates:

1. Create a PULL_REQUEST_TEMPLATE folder: Instead of a single markdown file, create a folder named PULL_REQUEST_TEMPLATE inside the .github folder.
2. Add multiple template files: Within this folder, create multiple markdown files for different templates, such as bug_fix_template.md, feature_request_template.md, etc.

Step 2: Use the pull request template

When you create a new pull request, GitHub will automatically use the single template from PULL_REQUEST_TEMPLATE.md. If there are multiple templates:

• GitHub will prompt you to choose a template if you use the GitHub interface.
• To use a specific template via URL: You can specify a template by appending the template query parameter to the URL, like so:

https://github.com/username/repository/compare/main...branch?template=feature_request_template.md

Step 3: Set a default pull request template

If you have multiple templates but want to set one as the default:

1. Rename your preferred template: Rename the file you want to use as the default to PULL_REQUEST_TEMPLATE.md and place it directly under the .github folder.
2. Other templates in the folder: Keep the rest of the templates in the PULL_REQUEST_TEMPLATE folder.

Managing templates

To manage and update your templates, simply edit the markdown files in the .github folder or the PULL_REQUEST_TEMPLATE subfolder. As your project evolves, periodically review your templates to ensure they still meet your needs and adjust them as necessary.

For more information on PR templates, see the official GitHub documentation.