Script Valley
Open Source Contribution: A Practical Guide
Communication and CommunityLesson 5.1

How to write a bug report that gets fixed faster

issue template, minimal reproducible example, environment information, expected vs actual behavior, error messages and stack traces, issue labels, severity vs priority

Bad Bug Reports Waste Everyone's Time

The phrase it does not work is not a bug report. A maintainer who cannot reproduce the bug cannot fix it. Your goal is to make reproduction trivially easy.

The Minimal Reproducible Example

Strip your bug down to the smallest possible code that still demonstrates it. Remove your business logic. Remove unrelated libraries. If it is a 500-line file and the bug appears in 10 lines, report 10 lines.

## Bug Report

### Summary
parseDate() returns NaN for valid ISO 8601 strings on Safari 17.

### Steps to Reproduce
1. Open Safari 17 on macOS Sonoma
2. Run: parseDate('2024-01-15T10:00:00Z')
3. Observe: returns NaN

### Expected
Returns a valid Date object matching the input timestamp.

### Actual
Returns NaN. isNaN(result) is true.

### Environment
- Library version: 2.4.1
- Browser: Safari 17.2
- OS: macOS 14.2 Sonoma

### Stack Trace
No stack trace -- silent NaN return.

Check existing issues before filing. Duplicate issues annoy maintainers. Search by error message, function name, and symptom keywords before opening a new one.

Following Up on Bug Reports

After filing a bug, you are not done. If a maintainer asks for more information, respond within 48 hours -- stale issues get closed. If you discover a workaround while waiting for a fix, post it in the issue thread. Other users hitting the same bug will find it. If the bug is fixed in a new release, verify the fix and close the issue with a confirmation note. Maintainers appreciate contributors who follow through. A bug report that goes from filed to verified-fixed with your involvement is a complete contribution, not just a complaint.

Up next

How to write a good feature request for an open source project

Sign in to track progress