I recently started contributing to an open source project, qit, which “let programmers find and listen to podcasts by topic“.
As I was going through issues to tackle to get started, I found out that many issues had just titles but no description of how to reproduce it or how the site should normally behave.
Thankfully, GitHub provides a way to encourage users for a better issue report.
The issue reported by THEjoezack above doesn’t provide a context regarding the issue reported.
What I mean by “context” is
- How to reproduce the error
- An expected behavior
- Environment such as browser, versions, and
- additional (optional) contexts such as screenshots/videos.
Below is the issue created with the context mentioned above.
When other developers see the issue, they can reproduce the error and how to fix it easier.
without having to ask the reporter back and forth for more info.
I gotta admit that I forgot to add a description on how to reproduce the error, only some URLs…
I am not smart enough to memorize what info to provide every time I create an issue.
Thankfully, GitHub made the process easy.
GitHub provides a way to create Markdown templates for issues such as
- Bug Report
- Feature Request
- Custom templates
I won’t go into details as the GitHub documentation is easy to follow.
You can add contexts in the template so that when a user creates a new issue, they are provided with pre-populated information about how to report an issue.
I reported the issue after setting up the template providing better experience for both issue reporter and the developer.
You can read more about issue templates on About issue and pull request templates.
Check out this video to see how issue template works after setting up templates.
For some reason, embedded youtube video isn’t working… 🤔
I found about the issue template from dotnet/cli project, which is s a huge project (with 200 contributors & 9k commits).
It’s amazing that the majority of issue reporters follow the template providing better context for the project contributors.
THEjoezack has create a feature request with a better context provided by the template.
And everyone’s happy 😎
Joe’s FOSSA feature request
If you have any questions, leave a comment (or please holla me on Twitter).
Need to keep up with a fast-moving software industry?