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, 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:
Creating a PR Template for Your Project
It's quite easy to generate a PR template for your project. Create a file named
PULL_REQUEST_TEMPLATE and place it one of three locations:
- The root of your project
An extension is optional, but Markdown (
.md) is supported. I've chosen to create a Markdown template so you can utilize 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.
I've created a pretty detailed PR template to use on your products. The elements below simply 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 a minimum level of rigor has been applied. Checklists are used in aviation 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 implementation file in
embedded-resources GitHub repository. The
PULL_REQUEST_TEMPLATE_example.md file contains the example template shown above.
PULL_REQUEST_TEMPLATE.md has been slightly modified for use in the