When you first start exploring open-source projects on GitHub, you might notice something: almost every active repository has an Issues tab.
But what is it actually for? Should you open an issue whenever you find a bug? What if you have an idea for a new feature? And if you already know how to fix something, should you open an issue first or go straight to a pull request?
I used to think that GitHub Issues were solely for project owners to track their own tasks 🫣, but I learned that anyone can open an issue to report a bug, suggest a feature etc..
Let's break it down.
What is a GitHub Issue?
A GitHub Issue is a place to report problems, suggest improvements, ask questions about a project, or discuss work that needs to be done.
Think of it as a shared record of something that needs attention. Instead of keeping ideas in your head or discussing problems in scattered messages, you create a place where contributors and maintainers can understand the context and discuss possible solutions.
I think issues are useful for more than bug reports. They can also help maintainers organize work, collect feedback, prioritize features, and coordinate contributions.
When should you open an issue?
There are a few common situations where opening an issue makes sense.
1. You found a bug 🐛
Suppose you are using an open-source application and notice that a button stops working after a particular action.
Before reporting it, try to reproduce the problem and check whether it has already been reported.
A useful bug report should explain:
- What you were trying to do.
- The steps needed to reproduce the problem.
- What you expected to happen.
- What actually happened.
- Any relevant error messages or screenshots.
For example, instead of writing:
"This button is broken."
You could write:
Title: Analyze button remains disabled after recording stops
Description:
Steps to reproduce:
- Start recording audio.
- Stop the recording.
- Observe the Analyze button.
Expected behavior: The Analyze button becomes available once recording has finished.
Actual behavior: The button remains disabled, preventing the user from analyzing the recorded audio.
This gives maintainers something concrete to investigate.
2. You have an idea for a new feature
You don't need to find a bug to open an issue. Maybe you are using a library and think it would be useful if it supported a new configuration option. Or perhaps you are contributing to a project and see an opportunity to improve the user experience.
An issue lets you explain the idea before anyone spends time implementing it.
For example:
Title: Add a sound discovery card to display classification results
Description:
It would be useful to display each sound classification result in a dedicated discovery card.
The card could show the predicted sound label, confidence score, and a short explanation of the result.
This could make the classification output easier to understand and give users a more engaging way to explore their recordings.
Would this feature fit the project's current direction?
Notice that this is a proposal, not a demand. The maintainers may suggest a different approach, ask for more details, or decide that the feature doesn't fit the project's goals. That's part of open-source collaboration.
3. The documentation needs improvement
Sometimes the code works perfectly, but the documentation doesn't.
You might find an outdated installation command, a broken link, a missing explanation, or an example that no longer works.
These are valid things to report, too.
For small, obvious documentation fixes, you may be able to submit a pull request directly. For larger changes or unclear expectations, opening an issue first can help you understand what the maintainers want.
4. You want to discuss an approach before writing code
Imagine that you want to add a feature, but there are several possible implementations.
Should you introduce a new dependency? Should the feature be handled by an existing module? Would the change make the project harder to maintain?
This is a good time to discuss the idea before implementing it, especially if the change is substantial.
A short conversation with maintainers can prevent you from spending hours building something that doesn't fit the project's architecture or priorities.
Issue vs. Pull Request vs. Discussion
These three GitHub features are related, but they serve different purposes.
Issue: Describes a problem, task, or proposal that needs attention.
Pull Request (PR): Proposes code or other repository changes for review and merging.
Discussion: Provides a space for open-ended questions, ideas, and community conversations when the project has GitHub Discussions enabled.
A simple way to remember the difference:
- I found a problem → consider opening an issue.
- I have an idea that needs feedback → consider an issue or discussion, depending on the project's conventions.
- I have a proposed change ready for review → open a pull request.
These aren't strict rules for every project. Some projects prefer discussions for feature proposals, while others use issues for almost everything. Always check the repository's guidelines.
Should you always open an issue before making a change?
No.
If you find a typo or a broken link and the fix is obvious, you may be able to submit a small pull request directly. However, for a significant feature, architectural change, or improvement that could affect the project's direction, discussing it first is often a better approach.
Before opening an issue or starting work, take a few minutes to:
- Read the README and look for a
CONTRIBUTING.mdfile. - Search existing issues, including closed ones.
- Check whether the project uses issue templates or specific labels.
- Look at the project's contribution guidelines.
- Explain your idea clearly and ask for feedback when needed.
sample c. guideline
This helps prevent duplicate reports and unnecessary work.
What makes a good issue?
A good issue makes it easy for someone else to understand what needs attention.
Here are a few principles I try to keep in mind:
Be specific. Describe one problem or proposal clearly rather than combining several unrelated topics.
Provide context. Explain why the issue matters and what you were trying to achieve.
Show what you tried. For bugs, include reproduction steps and relevant errors. For feature requests, explain the use case.
Keep it concise. Include the information needed to understand the issue without adding unrelated details.
Be open to feedback. An issue starts a conversation. It doesn't guarantee that a feature will be implemented exactly as proposed.
Also, avoid opening duplicate issues. If someone has already reported the same problem, adding useful information to the existing conversation is usually more helpful.
What happens after you open an issue?
Opening an issue is the beginning, not the end.
A maintainer might ask for more information, label it, assign it to a milestone, invite contributors to work on it, or close it if it is a duplicate or falls outside the project's scope.
Sometimes an issue leads to a pull request. Sometimes the discussion reveals that the proposed feature isn't needed. And sometimes the issue simply documents a problem for future reference.
If you solve the problem yourself after opening the issue, share the solution and update or close the issue when appropriate.Not every issue needs to become code to be useful.
One thing that confused me at first was why some issues remain visible even after the problem has been fixed. I learned that fixing a problem doesn't automatically remove its issue from GitHub. The issue usually needs to be closed by someone with the appropriate permissions, often after the related pull request is merged or the fix is verified. Closed issues remain in the repository's history, so people can still refer to them later.
A small but important part of open source
A well-written issue can save maintainers time, help another contributor find their first task, and turn a vague idea into a concrete improvement.
So the next time you notice something that could be better in an open-source project, don't immediately jump into the code.
Take a moment to understand the problem, check whether it has already been discussed, and decide whether an issue is the right next step.
Resources
Top comments (3)
Nice explanation, Gülnur! 😄
One thing I’ve learned while maintaining my own projects is that a good issue isn’t just a bug report. It’s also a record of why something needed to change.
And sometimes, the most valuable contribution isn’t writing code, but asking the right question before anyone starts coding.
Thanks for sharing! 🚀
Thanks for the comment 😊 I’m learning that open source is just as much about communication as it is about code
Exactly, Gülnur! 😊 And that’s one of the nicest things about open source. We don’t just learn from the code, we learn from each other.
Keep exploring and sharing your experiences! 🚀