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.

A good issue is detailed

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.

A good issue has a single responsibility

An issue describes a single problem or feature. If an issue touches multiple topics, it should be split.

A good issue is well formatted

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.

A good issue is polite

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.

A good issue creates a human connection

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.