Three years ago I maintained my first open source project for Hacktoberfest. As a first-time maintainer, I underestimated the time and effort it would take to write good issues for my contributors. What I also learned that year was that writing issues is an important form of communication, and, as a contributor, it can be a valuable skill to develop to create relationships and support maintainers. If you’re trying to get involved in open source, one way to get started is by writing issues that report bugs, request features, or suggest improvements.
Understanding the Purpose of the Issue
Issues are often a starting point for communication. It’s an opportunity to communicate with maintainers or for maintainers to communicate needs to contributors. There’s usually one main idea per issue with an explanation. For example, a bug report would address one bug. A feature request would outline one feature.
Elements of a Good Issue
A good issue should have several key elements that help to clearly and concisely communicate the problem or suggestion. These elements include:
- Clear and concise title: The title should describe the issue in a way that is easy to understand.
- Detailed description: The description should include a detailed explanation of the issue. It’s important to use clear and concise language, be specific, avoid assumptions, avoid vague or ambiguous language, and be respectful and professional. Lastly, provide additional information as needed to clarify the issue.
- Visuals: Screenshots, gifs, videos, or other visuals can be helpful in illustrating the problem.
- Contextual information: Provide any additional information about the environment or system affected by the issue.
- Proposed solution: If you have an idea for how to address the issue, include it in your issue.
Elements of a Good Bug Report
For bug reports, you should generally also include the following information:
- Steps to reproduce the bug
- Your work environment (operating system, etc.)
- The browser you’re using
- Any applicable screenshots, video reproduction, code, or context
Elements of a Good Feature Request
For feature requests, you need to help the maintainer understand why the feature is important. You should generally include the following information:
- Type of feature (docs, refactor, style, code feature, etc.)
- The current state of the application and the solution you suggest with your feature
- Any additional context of information, including alternatives you’ve considered
Issue templates
Some repositories will use issue templates to help guide you through writing an issue. For example, at OpenSauced, we have templates for bug reports and feature requests (shown below). Templates help to ensure the maintainer gets all the information they need to communicate with contributors. If there are templates, it’s important to use them rather than start with a blank issue.
Example Walkthrough
Sometimes the best way to learn is by looking at examples, so we’re going to walk through this Remix issue from Nick Taylor.
We’ll go through each element of a good issue and bug report.
Clear and concise title
TypeError: Body is unusable when using Remix(experimental-netlify-edge) Actions
Detailed description & Steps to reproduce the bug
In the issue, Nick covers some key steps:
- What version of Remix he's using
- Steps to Reproduce, including a numbered list, code snippets, screenshots, and a link to a Discord discussion with more context.
- Expected behavior
- Actual behavior with a screenshot of the error message.
Visuals
Within the description of the issue, there's a screenshot of what it looks like when it runs locally and an image of how it would look in Postman.
Proposed solution
Although the initial issue doesn't include a proposed solution, Nick explores what's happening and maintains communication in the comments. As part of the investigation, he created a repository to help the maintainers check it out, and shared his approach in his comment.
Work Environment
Nick shares the version of Remix, the versions of Node he tried, and includes that the Netlify CLI was installed.
Conversation
Nick didn’t end the issue with the bug report. If you scroll beyond the issue, you’ll see that he continued the conversation, referencing a conversation in the organization Discord, and his investigation into the bug and solutions. He makes updates as he finds more information, providing code snippets for contextualization, and tags maintainers as part of the conversation as well as others who have contributed.
Best of all, he supports the team member who helped with the fix.
Writing good issues is an important part of effective communication both in how you construct the issue and how you communicate once the issue has been opened. It’s a great way to demonstrate your communication and investigation skills. And if you’re trying to get into open source, remember, good first issues don’t exist, unless you make them yourself 😉
Top comments (12)
:O you can inputs in the issue form?
Yep! I think this post links to how to do that and some examples.
Awesome! Thank you! With this I can make issues and PRs way easier to complete.
We've been trying to gain traction for our issues on GitHub. Following these tips might increase the appeal to them, thanks!
I hope they do! Let me know if it works out.
The artwork used in this article is awesome, where did you get it?
The image at the top was generated from midjourney!
Great prompting! I never seem to be able to get that kind of quality when dealing with AI. Or perhaps Im just impatient.
Here's the prompt I used: a girl writing a detailed note with circuit imagery behind her, neon colours, studio ghibli. Hayao Miyazki --v 5 --ar 100:42
Great share! Framing some of these screenshots would've been chef's kiss! @bekahhw I've built a simple OSS tool for creating engaging screenshots with ease. Check it out and let me know what you think! Cheers!
github.com/ekqt/screenshot
This is an extremely light version of what it takes to write an issue. Missing are things like severity, versioning of program under test, versioning of OS or browser, etc.
There are areas that should be selected when writing an issue, things like UI/UX, etc. and much more, so when the Dev team reviews the issue they know where it is and how to repeat it. Example: a large printer company I was testing install software for had extreme concerns for logo and naming. Colors and the visual aspect had to be 100% correct but a small error in spelling was something low on the totem pole, but still needed to be done eventually.
Step by step instructions must always be included.
Testing is saturated with wrong ideals of testing and what it actually takes to perform excellent testing.
There was a local mid level manager that told a local college she could create qualified testers with a two day a week six week course. I almost wet my pants laughing so hard when the head of that college's adult courses told me. Some manages have even said it's something monkeys could do. Of course the product they are covering is usually over budget, over the scheduled release date and bad!
I think I may add some content in the future.
Thanks
That’s a great example. Thanks for sharing!