How to Record a Bug Report Developers Can Actually Use

Write the reproduction spine first

Mozilla asks reporters to describe steps to reproduce, actual results, and expected results, and to include one problem per report. GitHub similarly recommends clear reproduction steps and contextual information in issue forms. See the primary source.

• A short, specific summary.
• Numbered steps beginning from a known state.
• Expected behavior and actual behavior.
• Frequency: always, intermittent, or observed once.
• Environment: app version, distribution, desktop session, relevant hardware, and display setup.

Record the complete trigger

Begin early enough to show the known starting state. Perform the smallest reliable sequence without unrelated exploration. Leave the failure visible long enough to inspect, then show any error surface or relevant log excerpt without exposing secrets.

Protect private data before capture

A recording can reveal information outside the reported application, so minimize what enters the frame before capture. Access controls reduce distribution risk but do not replace data minimization.

• Use a test account and synthetic records.
• Close email, chat, password managers, terminals with tokens, and unrelated browser tabs.
• Disable notification previews.
• Crop or rerecord rather than relying on a fleeting cover-up.
• Review the entire exported file and its thumbnail before sharing.

Narrate state changes, not every pointer movement

Say what precondition matters, what you expect, and the exact moment the result diverges. If narration is included, add accurate captions; W3C guidance requires captions for prerecorded synchronized media at WCAG Level A. See the primary source.

Share for diagnosis

State who has access, how long the artifact should remain available, and whether downloading is appropriate. Ask for a concrete next response such as confirmation, a log request, or whether another environment reproduces it. Screenix hosted sharing supports configurable access, while local export lets you use the project's existing issue-tracker or storage controls.

Copyable bug-report template

• Summary: [one sentence]
• Environment: [app version, distro, desktop/session, hardware/display details]
• Starting state: [account/data/configuration]
• Steps: 1. […] 2. […] 3. […]
• Expected: […]
• Actual: […]
• Frequency: […]
• Recording: [link, access/expiry note, useful timestamps]
• Additional evidence: [logs/screenshots, with secrets removed]
• Requested response: [confirmation or next diagnostic step]

Keep reading

Continue with the part of the workflow that matters next:

• Decide whether async video is appropriate
• Prepare and verify a clean recording
• Fix missing evidence from audio