GitHub Issue & Bug Report Length Guide
A well-written GitHub issue is the difference between a bug that gets fixed in days and one that languishes for months. Open source maintainers triage dozens or hundreds of issues weekly, and the quality of your report directly determines how quickly it gets attention. Issues that are too brief lack the information needed to reproduce the bug; issues that are too verbose bury the critical details in walls of text. This guide covers optimal lengths for issue titles, bug reports, feature requests, and the templates that maximize maintainer response rates.
Issue Title Best Practices
The issue title is the first (and sometimes only) thing a maintainer reads when triaging. It appears in notification emails, search results, and project boards.
| Title Quality | Length | Example |
|---|---|---|
| Too vague | 1–3 words | "Bug" or "Not working" |
| Good | 6–12 words | "Login fails with 500 error when using SSO on Firefox" |
| Great | 8–15 words | "[Bug] CSV export truncates rows exceeding 10,000 in v3.2.1" |
| Too long | 20+ words | Gets truncated in most interfaces |
Aim for 8–15 words (50–80 characters). Include the component or feature affected, the symptom, and any relevant version or environment info. Prefix with [Bug], [Feature], or [Question] for instant categorization.
Bug Report Structure
| Section | Word Count | Content |
|---|---|---|
| Summary | 20–40 words | One-paragraph description of the issue |
| Steps to reproduce | 30–80 words | Numbered steps, as specific as possible |
| Expected behavior | 10–25 words | What should happen |
| Actual behavior | 10–30 words | What actually happens (include error messages) |
| Environment | 15–30 words | OS, browser, version, relevant config |
| Screenshots / logs | 5–15 words + attachments | Visual evidence or error output |
Total: 90–220 words. This range provides enough detail for reproduction without overwhelming the reader. The most critical section is "Steps to reproduce" — if a maintainer can't reproduce the bug, it won't get fixed.
Feature Request Structure
- Problem statement (30–60 words): What pain point or limitation does this address? Start with "As a [user type], I want to [action] so that [benefit]."
- Proposed solution (40–80 words): Your suggested implementation. Be specific but acknowledge that maintainers may have better approaches.
- Alternatives considered (20–40 words): Other approaches you've thought about and why they're less ideal.
- Additional context (20–40 words): Use cases, mockups, or links to related issues.
Total: 110–220 words. Feature requests that clearly articulate the problem (not just the solution) are far more likely to be accepted.
Issue Templates That Work
GitHub issue templates standardize submissions and ensure reporters include essential information. Effective templates balance structure with flexibility.
- Keep template prompts short: Each section prompt should be 5–15 words. "Describe the bug in 1–2 sentences" is better than a paragraph of instructions.
- Use checkboxes for common info: "- [ ] I searched existing issues" saves time and reduces duplicates.
- Include version/environment fields: Pre-formatted fields for OS, browser, and version reduce back-and-forth.
- Limit required sections to 4–6: Templates with 10+ sections discourage reporting. Keep it focused.
Pull Request Description Length
| PR Type | Description Length | Key Elements |
|---|---|---|
| Bug fix | 50–150 words | Issue link, root cause, fix approach, testing |
| Feature | 100–300 words | Motivation, implementation details, screenshots |
| Refactor | 75–200 words | What changed, why, performance impact |
| Documentation | 30–75 words | What was updated and why |
| Dependencies | 25–50 words | What was updated, breaking changes, changelog link |
Conclusion
GitHub issue titles should be 8–15 words (50–80 characters). Bug reports work best at 90–220 words with clear reproduction steps. Feature requests should be 110–220 words, leading with the problem rather than the solution. PR descriptions range from 25–300 words depending on complexity. Use Character Counter to keep your issues concise and effective.