A GitHub Pull Request Template for Your Projects

Updated: 2019-03-02

I've been thinking about creating GitHub issue and pull request templates for my own projects. These templates auto-populate the issue/pull-request description field and provide a skeleton framework that you can fill out. I like these templates every time I come across them, since they help provide a baseline standard of informational quality and organizational rigor. I've also been thinking about incorporating checklists into pull requests as a reminder to myself (and other developers).

I recently discovered that GitHub markdown supports [task lists][3], which finally makes my checklist dream a reality. You can add check boxes to your PR and issue templates, and as they get checked off, you can see the status change:

Issues and pull requests with task list items defined will summarize the task list on the pull request listing and any cross reference.

Issues and pull requests with task list items defined will summarize the task list on the pull request listing and any cross reference.

Table of Contents:

  1. Creating a PR Template For Your Project
  2. My Template
  3. Example Template File
  4. Further Reading

Creating a PR Template for Your Project

It's quite easy to generate a PR template for your project. Simply create a file named PULL_REQUEST_TEMPLATE and place it one of three locations:

  • The root of your project
  • .github folder
  • docs folder

An extension is optional, and GitHub supports Markdown (.md) files. I've chosen to create a Markdown template so you can use features like Markdown formatting, @-mentions, and task lists.

Once GitHub detects the PULL_REQUEST_TEMPLATE file, it will auto-populate new PRs with the contents.

My Template

I've created a pretty detailed PR template to use on your products. The elements below cover details I like to understand for each PR:

  • What is this change?
  • What does it fix?
  • Is this a bug fix or a feature? Does it break any existing functionality or force me to update to a new version?
  • How has it been tested?

I've also added a checklist section to the end of the template. Before submitting / approving a PR, I want to be sure that developers are applying a minimum level of rigor. The aviation industry uses checklists to ensure correct process and reduce accidents. I don't see why software developers can't use them too!

You can add or remove details as needed for your own specific use cases.

# Description

Please include a summary of the change and which issue is fixed. 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 own 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 Template File

You can find an example PULL_REQUEST_TEMPLATE.md file in templates GitHub repository.

Further Reading

Change Log

  • 20190302:
    • Improved grammar
    • Added table of contents
    • Updated links to refer to templates repository
    • Added additional links

Related Articles