A good GitHub issue gives a maintainer everything they need to reproduce your problem and nothing they don’t. Before you open one, search existing issues; then use the repository’s issue template, write a specific title, and include a minimal reproducible example, your exact versions, and what you expected versus what actually happened. Keep it to one problem per issue, format it with markdown code fences, and be patient – most maintainers are volunteers. An issue someone can reproduce in two minutes is an issue that gets fixed.
How to Write a Good GitHub Issue: Step by Step
- Search open and closed issues first. Your bug may already be reported, fixed, or explained – comment there instead of opening a duplicate.
- Check CONTRIBUTING.md and the issue templates. Many projects route questions to Discussions and reserve issues for bugs and features.
- Pick the right template and one problem. Choose “bug report” or “feature request,” and file a separate issue for each distinct problem.
- Write a specific title. Summarize the actual symptom, like a good commit message – not “It doesn’t work.”
- Add a minimal reproducible example. Provide the smallest runnable snippet, sample repo, or exact steps that trigger the bug.
- State expected vs. actual behavior and your environment. Include the exact package version, OS, and runtime, plus the full error or logs in a code block.
- Submit, then stay responsive. Answer the maintainer’s follow-up questions so the issue doesn’t go stale.
Do’s and Don’ts
Do:
- Search existing open and closed issues before filing.
- Follow the repo’s issue template and contributing guide.
- Write one clear, specific issue per problem.
- Include a minimal reproducible example and exact versions.
- Use markdown code fences for code, logs, and stack traces.
Don’t:
- Open a duplicate without checking first.
- File a vague “doesn’t work” issue with no reproduction.
- Bundle several unrelated bugs into one issue.
- @mention or DM maintainers to demand a fast fix.
- Pile on “+1” or “me too” comments – use a 👍 reaction instead.
Search Before You File
Open issues are only half the picture – search the closed issues too. A closed issue often holds the fix, the workaround, or the maintainer’s reason for “won’t fix.” If you find a matching open issue, add your reproduction details or environment there instead of opening a duplicate; that consolidates the signal maintainers use to prioritize. Use GitHub’s issue search with qualifiers like is:issue your error text to cut through the noise.
Use the Issue Template (and the Right Channel)
Most established repositories ship issue templates – a bug-report form, a feature-request form, sometimes a blank-issue option that’s deliberately turned off. Fill the template out completely instead of deleting the prompts; each field is there because maintainers got tired of asking for it.
Before that, skim CONTRIBUTING.md. Many projects send usage questions to GitHub Discussions, a community forum, or Stack Overflow, and keep the issue tracker strictly for bugs and feature requests. Posting a how-to question as an issue in those repos usually just gets it closed with a link to the right place.
The Heart of a Good Issue: A Reproducible Example
Everything else is secondary to this one question: can the maintainer reproduce your problem? Give them a minimal reproducible example – the smallest runnable snippet, sample repository, or exact sequence of steps that triggers the bug on a clean setup. “It crashes sometimes” is not actionable; “running npm test on a fresh clone of this 15-line repro throws the stack trace below” is.
If you’re reporting a bug rather than requesting a feature, drop your example straight into our bug report template – its “Steps to reproduce” and “Environment” fields are built for exactly this.
Include Versions and Environment
“Latest” is not a version. Give the exact package version (or commit SHA), the operating system, and the language or runtime version – v2.4.1, macOS 14.5, Node 20.11. Bugs are frequently version-specific, and a maintainer who can’t tell which release you’re on will waste a round trip just asking. Paste the full error message and any relevant logs; a truncated error usually hides the line that actually matters.
Format It Like You Mean It
GitHub issues are markdown, so use it. Wrap code, commands, and stack traces in triple-backtick fences with a language hint for syntax highlighting. Collapse very long logs inside a <details> block so the issue stays readable. Label the key parts – Expected, Actual, Steps to reproduce – and link to specific lines of code with permalinks (press y on GitHub to get a commit-pinned URL). A clean, scannable issue gets triaged faster than a wall of text.
Remember Who’s on the Other End
Most maintainers are unpaid volunteers working on the project in their spare time, and that shapes the etiquette. Don’t @mention or DM them to demand a fix, and don’t add “any update?” comments that only create noise. Skip “+1” and “me too” entirely – add a 👍 reaction to the original issue so maintainers can gauge demand without a flood of notifications. Comment only when you have something new: another reproduction, a different environment, or a workaround.
And if you suspect a security vulnerability, don’t open a public issue at all. Use the repository’s private security reporting – usually a SECURITY.md policy or GitHub’s “Report a vulnerability” tab – so the flaw isn’t broadcast before it’s patched.
The Formula Still Applies
A great GitHub issue is just the Skip The Ask formula in a developer’s context:
- Your situation – the project, version, and environment you’re running
- Your specific report or request – the exact bug or feature, in a clear title
- Relevant details – a minimal reproducible example, expected vs. actual behavior, and the full error
Give maintainers a problem they can reproduce and you’ve done 90% of the work toward getting it fixed.
Asking a how-to question instead of reporting a bug? Our Stack Overflow guide covers that case. For the universal principles behind every platform, see our complete guide to asking better questions online.