Writing Issues and Bug Reports

2011. The V8 team has been hunting an intermittent JIT bug for three weeks. It reproduces in 1 out of 50 runs. Then an issue arrives from an engineer in Seoul: 7 lines of JavaScript that break the JIT optimizer reliably, every single time. Expected output, actual output, V8 version. Forty-eight hours later: `FIXED`. One properly written issue did what three weeks of work by three engineers could not.

• React receives 2000+ issues per year - most without an MRE close in weeks without a fix
• Chromium data: issues with MREs are fixed on average 60% faster
• Node.js contributing guide explicitly states: issues without minimal repro will not be reviewed
• Vite requires a StackBlitz reproduction - without one, the `needs-reproduction` label is auto-applied

Anatomy of a Good Bug Report

2011. Chromium issue tracker. An engineer from Seoul opens a bug titled **"Array sort produces wrong results for specific float comparator"**. Attached: 7 lines of JavaScript, the expected output, the actual output, the V8 version. Within 48 hours, three Google engineers who had been hunting an intermittent JIT bug for three weeks close the ticket: `FIXED`. One well-written issue accomplished what three weeks of debugging could not.

On that same tracker, thousands of issues live under the title "It doesn't work on my machine". Closed in two minutes with label `needs-info`. The difference is not the severity of the bug - it's that the first issue can be immediately acted on, and the second cannot.

Five Required Elements

The structure is deliberate. **Reproduction steps** are the test the maintainer runs locally. **Expected vs Actual** communicates what broke at a glance. **Environment** cuts off 80% of "what version are you on?" follow-ups. Without any single element, the maintainer writes a clarifying comment, and the issue sits open another week.

**Why regression info is valuable:** if the version where the bug first appeared is known, the maintainer can run `git bisect` and pinpoint the exact commit in 10 iterations instead of manual history spelunking. "Works in 3.1.8, broken in 3.2.0" is already half the diagnosis.

Issue titles are their own craft. Formula: `[component] action leads to result under condition`. Bad: `Error with imports`. Good: `[plugin-react] Fast refresh breaks when component uses custom hooks from external package`. The second version conveys: where (plugin-react), what (fast refresh), under what condition (custom hooks). A maintainer knows in one second whether it falls in their area.

Minimal Reproducible Example

A minimal reproducible example (MRE) is the smallest piece of code that reliably triggers the bug. The word **minimal** is the key. Not "my 50,000-line application" - exactly those 10-20 lines where removing any single line makes the problem disappear.

There is an interesting property of the process: attempting to create an MRE solves the problem before the issue is even opened in roughly 30% of cases. During isolation, it turns out the problem was in the reporter's own code, not the library. Another 20% - the bug is already known and closed, found by searching the tracker. The remaining 50% are genuine new bugs - and for those, an MRE speeds up the fix by 5-10x.

Tools for fast MREs: **CodeSandbox**, **StackBlitz**, **Replit** - isolated environments in 2 minutes, shareable as a link. For Node.js libraries, a gist or minimal repo with one `package.json` and `index.js` works. For browser bugs - codepen or jsbin. Any of these is better than a link to a private repository with a 10-step setup guide.

**Do not attach the whole project.** A maintainer will not clone a 200 MB private repository to reproduce a bug. This rule is unwritten but reliable: no MRE, issue waits. The bottleneck for most bugs that never get fixed is the inability to reproduce them. MRE removes that bottleneck.

Feature Requests and the Maintainer's Perspective

A feature request is not a wishlist item. Maintainers see hundreds of requests per year. The ones that get accepted solve a real problem for enough people and fit the project's architecture. A request that says "add support for X" with no context gets labeled `needs-discussion` and sinks.

Core principle: describe the **problem**, not the **solution**. The maintainer may know a better implementation path. A feature request that starts with a concrete symptom ("rendering 10,000 rows blocks the UI thread for 1.8 seconds on a mid-range device") is more compelling than one that jumps straight to a proposed flag. The first format invites discussion of multiple approaches.

Inside Triage: What Maintainers Actually Do

A maintainer on a large project processes 10-30 new issues per week. The first 30 seconds: reproduce or request info. Issues without an MRE or with unclear descriptions get labeled `needs-info` and wait. This is not hostility - it is time management. A well-written issue shows respect for someone who is often working for free.

**Searching for duplicates is mandatory.** GitHub search by keywords, filter by open and closed issues. A duplicate of an already-closed issue with a solution wastes everyone's time. If a similar issue is found, commenting on it is better than opening a new one. Labels like `duplicate`, `wontfix`, `good first issue` are the project's communication protocol - read them before opening.

Key Ideas

• Bug report: reproduction steps + expected vs actual + environment + MRE - five required elements
• MRE - the smallest code that reliably triggers the bug; creating one solves 30% of issues before they are opened
• Feature request describes the problem, not the solution - the maintainer may know a better approach
• Issue title formula: [component] action leads to result under condition
• Searching for duplicates before opening is mandatory - respect for the community's time

Related Topics

Issue written - next step: turn it into a PR.

• Fork and PR Workflow — Technical process of creating a PR after an issue
• Anatomy of a Great Pull Request — A good issue becomes the foundation of a PR description
• Working with Maintainers — Issues are the primary communication channel with maintainers

Вопросы для размышления

• Find any closed issue in React or Vue with label `needs-more-info`. What specifically was missing? How would you write it correctly?
• Why does the process of creating an MRE often solve the problem before an issue is opened? What mental process takes place?

Связанные уроки

• oss-04-fork-pr-workflow — Fork workflow context before writing issues
• oss-06-great-pull-request — A good issue is the first step toward a good PR
• oss-07-code-review — Code review demands the same precision as issue writing
• oss-09-maintainers — Working with maintainers starts with a well-written issue
• oss-08-community — Community etiquette shapes how issues are written
• se-02