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:
Table of Contents:
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
.githubfolderdocsfolder
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 modulesExample Template File
You can find an example PULL_REQUEST_TEMPLATE.md file in templates GitHub repository.
Cool to see the checbox statuses updated..
I would encourage some of those check points to be automated in the CI pipeline (with status checks or github actions).
Totally right, half of that can be removed with CI in the picture.