A good issue
| 1 min read
Maintaining a number of open source projects comes with a number of issues. Reporting a good issue will result in a more engaged approach from project maintainers. Don’t forget: there’s a human behind every project.
Report issues as detailed as possible. Share code. Share configuration. Share hardware setup. Share screenshots. Share stacktraces. Every assumption the maintainer makes, takes away from their ability to help.
If the issue can be proven, prove it. Submit a failing test or concrete steps to reproduce it.
An issue describes a single problem or feature. If an issue touches multiple topics, it should be split.
Use code blocks for code. Check indentation for pasted code. Check for syntax errors. When unsure, use a code linter or fixer before reporting. The easier it is for the maintainer to read code, the easier it is for them to understand it.
Stay polite in all circumstances. There’s no accountability in free open source software. Respectful communication is paramount.
When reporting an issue, it’s not uncommon for you to be in a difficult position. Don’t hurl that frustration towards the project maintainer.
Without a person behind an issue, it’s hard for the maintainer to feel empathy. Simply saying “Hello”, or “I would appreciate some help on this matter” creates a human connection.
I occasionally send out a newsletter with personal stories, things I’ve been working on in the past month, and interesting things I come across.
Pinky swear that I won't use your data for any other purposes. Your email address will be stored on Mailchimp and nowhere else.