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.