The more information you have on an issue or pull request (PR), the better you are able to work on it. The more is not in terms of the length, but any related info that may help you. Sometimes, while reporting a bug, users assume a few things but they might be vital for the maintainer.
For example, a user may report an issue on your open source project. Add description, screenshots, and steps to reproduce it. But he might miss info like operating system, version of the tool, and other environment variables that might be useful for your project. 🧐
🔥 Fortunately, GitHub has this feature called templates to help us. We can create a set of templates to request the information we might need for a specific issue/PR. That's what I'm going to discuss in this Today.
🚦 Issue Templates
Issues are a way of reporting a bug, requesting a feature, an update, or do some discussion on GitHub. Chances are, if you don't have a template in place, you might end up with something like this:
🧐 A mystery bomb fell on to you. You know someone is having an issue with the sign-in but you don't know how and why. It's frustrating.
🚀 Creating Templates
A template is just a markdown file that gets automatically populated in the description section of an issue/PR. You can specify different headings, ask for information you need, add labels, add a generic title, and even assign a reviewer. This way, you might be able to get enough information to help people. 💯
To create an issue template, go to Settings > Issues >> Set up templates in your GitHub repo. Then add a custom template. You can also choose the default bug report and feature request templates, and modify them according to your needs.
The best part is, you can add multiple templates for the issues. I suggest adding at least two templates for the issues:
- Bug Report
- Feature Request
That's what we have at Daily. Now, when a user creates an issue, he gets to choose from the templates:
And if the user selects one of the options, let's say Bug Report, this is how the next screen looks like:
This is how you can streamline the issue-reporting in your project using the GitHub templates. The markdown files for your templates are stored in root at .github/ISSUE_TEMPLATE directory of your repo. If you have a single template, you can simply put the markdown file for that in .github/ folder by naming it ISSUE_TEMPLATE.md and it's automatically applied.
🎯 Pull Request Templates
Just like issues, sometimes we receive a PR which looks like this:
PRs are important, but figuring out everything on our own by looking at the code is hard. It becomes much easier if we have a description of what this PR does and how it can be verified. That's where we need PR templates.
Usually, I suggest to ask at least the following three questions in a PR template:
- What does this PR do?
- What issues does this PR close? Or if it adds any new feature.
- How can the code be tested?
🍭 Creating PR Templates
Unlike issue templates, you have to create PR templates manually. To create multiple PRs, store the .md files inside a PULL_REQUEST_TEMPLATE folder. The folder can be either in .github folder or docs folder at the root of your repository.
Usually, a single PR template PULL_REQUEST_TEMPLATE.md is recommended.
🙌 Wrap Up!
Having proper templates in place helps you save your time in maintaining your project. It helps to streamline the flow and make things consistent across the repository.
You can always take a look at our GitHub repo to see the templates we are using to track the issues. Feel free to contribute if you want to.
Don't forget to share your thoughts on GitHub templates in the comments below.
Thanks to Daily developers can focus on code instead of searching for news. Get immediate access to all these posts and much more just by opening a new tab.
Top comments (0)