Github Templates to make your life easier
When Github started doing templates, I’d just started pushing to get some sanity and consistency for our Peer Review process at work, so, needless to say, it came as a welcome addition to their service. Utilizing the template system can help you establish rules for submissions to your own projects, and ensure that the appropriate contextual information is included when submitting an issue or pull-request, so you won’t be left scratching your head when someone posts ‘Such-and-such feature is broken’ to your issues list.
The first template we’ll be discussing is an issue template. The issues template should be installed in your project as a file named issue_template.md, and stored somewhere within your project. (I personally recommend .github/issue_template.md) As the extension of the filename suggests, this is a markdown document… markdown being the markup language used on Github when you edit your readme, issue/pull-request descriptions, and comments. If you’re going to be on GitHub a lot, you’d do well to get familiar with it.
The reason why you want this template in your project is self-evident… you want people who are submitting issues to:
1) Check to make sure their issue has not already been submitted by someone else
2) Ensure the user has been following the proper procedure to get your app up and running properly
3) Ensure the when/where/why/how and who of the error is explained in a way that you’re going to get the most out of when triaging those incoming bugs.
Instructions for creating your . own issue_template.md file can be found here.
The second template, as with the first, is also a markdown document: pull_request_template.md, and can be stored in the same folder as issue_template.md. Instructions for creating this one are fairly similar to the last one we discussed, and a walkthrough to do so can be found here.
You’ll want a pull-request template to ensure contributors fully explain what’s going on, what’s been changed, and which issue this is intended to fix, or feature it’s intended to implement.
There are many ways you can go about wording your templates, depending on the level of detail you want contributors to include. For example, for the issue-template, you can include a checklist which users can fill out to tick off steps they need to fallow before submitting their issue. As for the PR template, here’s a gist of the one we use on our projects at my job:
The eagle-eyed faithful among you, when viewing the source of this document, will notice some marked similarities to the .gitmessage template I posted earlier this week. This is not by accident. When you utilize the .gitmessage template and combine it with a clean commit history (more on that here), Github will automatically populate the title and description of your PR with the text from your commit message (which is pretty cool, when you think about it… a nice touch on the part of Github’s developers). We don’t actually use an issue template on my projects at the moment, as our issues are tracked by Pivotal Tracker, rather than by GitHub’s own issue system; I’m ashamed to admit that I don’t have a gist to share with you for that one. However…
Some other great examples can be found here, including a template generator that will walk you through creation of either of these templates in the framework of a “choose-your-own-adventure” Lewis Carroll or H.P. Lovecraft-styled story. Utilizing these resources, I’m sure you’ll be able to find something that best fits your own projects’ needs.
