Chapter 4: Creating Your First Issue
Opening an issue is often the first visible interaction you have with a project.
A good issue helps maintainers understand a problem quickly and decide what to do next.
This guide focuses on writing issues that are useful, respectful, and actionable.
What an Issue Is (and Is Not)
An issue is:
- a problem report
- a proposal
- a discussion starter
An issue is not:
- a demand
- a support ticket
- a guarantee of implementation
Issues invite collaboration.
When to Open an Issue
Open an issue when:
- you found a bug
- documentation is unclear or incorrect
- a feature is missing
- behavior is surprising
- something feels inconsistent
If you are unsure, searching existing issues first is always the right move.
When Not to Open an Issue
Avoid opening an issue when:
- the documentation already answers the question
- the issue is purely personal preference
- the project explicitly discourages certain requests
- the topic is already actively discussed elsewhere
Respecting scope builds trust.
Checking Before You Write
Before creating an issue:
- search existing issues
- read the README
- check contribution guidelines
- review documentation
This prevents duplicates and shows consideration.
Understanding Issue Templates
Many projects provide issue templates.
Templates exist to:
- standardize information
- reduce back-and-forth
- help maintainers act faster
Follow them closely.
Writing a Clear Title
A good title:
- is specific
- describes the problem
- avoids vague language
Examples:
- “CLI crashes when config file is missing”
- “Documentation example fails on latest version”
Titles set expectations.
Describing the Problem
A clear issue description includes:
- what happened
- what you expected to happen
- why it matters
Avoid assumptions about intent or quality.
Focus on observable behavior.
Providing Reproduction Steps
If reporting a bug, include:
- environment details
- steps to reproduce
- minimal examples
- error messages or logs
Reproducibility determines actionability.
Including Context
Context helps maintainers decide faster.
Include:
- links to relevant documentation
- related issues or PRs
- screenshots or code snippets when helpful
Context reduces guesswork.
Proposing, Not Demanding
If suggesting a feature:
- describe the problem first
- explain the use case
- suggest an approach cautiously
Avoid prescriptive language.
Maintain flexibility.
Tone and Communication
Effective issues are:
- respectful
- neutral
- concise
- collaborative
Avoid:
- frustration-driven language
- blame
- sarcasm
Tone influences response quality.
After Opening the Issue
Once the issue is open:
- be ready to answer questions
- provide clarification if asked
- accept that priorities may differ
Silence does not imply rejection.
Understanding Maintainer Responses
Maintainers may:
- ask for more information
- redirect the issue
- close it with explanation
- accept it for future work
All outcomes are valid.
Issues as Contributions
Opening a good issue is a real contribution.
It:
- improves project quality
- saves maintainer time
- helps other users
- shapes future work
Not all contributions involve code.
What You Should Be Able to Do Now
You should now be able to:
- decide when to open an issue
- write a clear and helpful issue
- communicate respectfully
- handle responses constructively
This is a major step in open source collaboration.
Reflection
Ask yourself:
- What problem am I trying to surface?
- Is my issue clear without extra explanation?
- Would I understand this issue if I were a maintainer?
Clarity is empathy.
You've Completed Chapter 4
Well done! You've learned about creating your first issue.