What should a bug report contain?

Nine sections. The first four get the bug reproduced; the rest get it prioritised and fixed without a round trip back to the reporter.

Bug report template (markdown)

Copy this into your tracker, wiki, or a new document. Every section is an H2 so the rendered report gets a table of contents.

# Bug: <one line — what breaks, where, under what condition>

## Summary
Two or three sentences: what happens, who it affects, why it matters.

## Environment
- Product / version / build (commit if known):
- URL or screen:
- OS + browser or device:
- Account type / role / region:

## Steps to reproduce
1. ...
2. ...
3. ...

## Expected result
What should have happened.

## Actual result
What happened instead. Quote exact error text.

## Evidence
- Screenshot / recording:
- Request + response (status, body):
- Console or server log lines:

## Scope and impact
- Reproduces N/N times on <env>; not on <env/version>.
- Who is affected; how many reports so far.

## Workaround
What a user can do right now, or "none".

## Suspected cause (optional)
Only if you have a concrete lead — a PR, a commit, a config change.

What does a good bug report look like filled in?

A fictional but realistic one: a checkout page loses an applied discount when the quantity changes. Notice what makes it actionable — the build number, the SKU and promo code used, the request that returned the wrong body, the last build that worked, and the number of support tickets that match.

How do I turn the template into a GitHub issue form?

For a public repository, the same sections as a YAML issue form in .github/ISSUE_TEMPLATE/bug_report.yml. Required fields stop reporters from skipping the steps or the version; the free-text fields keep the markdown habits (numbered steps, fenced error text) intact.

# .github/ISSUE_TEMPLATE/bug_report.yml
name: Bug report
description: Something is broken
title: "Bug: "
labels: [bug, triage]
body:
  - type: textarea
    id: summary
    attributes: { label: Summary, description: What happens, who it affects, why it matters }
    validations: { required: true }
  - type: input
    id: version
    attributes: { label: Version / build, placeholder: "2026.09.04-1 (c81d2f7)" }
    validations: { required: true }
  - type: input
    id: env
    attributes: { label: Environment, placeholder: "Chrome 140 · macOS 15.6 · US" }
  - type: textarea
    id: steps
    attributes:
      label: Steps to reproduce
      value: |
        1.
        2.
        3.
    validations: { required: true }
  - type: textarea
    id: expected
    attributes: { label: Expected result }
    validations: { required: true }
  - type: textarea
    id: actual
    attributes: { label: Actual result, description: Quote exact error text }
    validations: { required: true }
  - type: textarea
    id: evidence
    attributes: { label: Evidence, description: Screenshots, request/response, logs }
  - type: textarea
    id: workaround
    attributes: { label: Workaround }

GitLab and Gitea use markdown description templates instead (.gitlab/issue_templates/Bug.md, .gitea/ISSUE_TEMPLATE/bug.md) — paste the markdown template above into those files as-is.

How do I share a bug report with someone who has no tracker access?

A customer, a vendor, a contractor, a release thread in Slack: paste the markdown on the Docs MD editor and share the link. From Claude Code or Cursor with the MCP server connected:

Write a bug report for the failing checkout test using the nine-section
template (build, steps, expected, actual, evidence, scope, workaround), then
share it with a 7-day expiry and give me the reading link.

From a shell or CI:

curl -s -X POST https://docs-md.com/api/share \
  -H "Content-Type: application/json" \
  --data-binary @<(jq -Rs '{content: ., filename: "bug-report.md", expiry: "7d"}' bug-report.md) \
  | jq -r '.url'

The reader opens a rendered page with headings and a sidebar table of contents. The /raw/<id> URL returns the markdown itself for pasting into a ticket or feeding to an assistant.

What should stay out of a bug report?

• Several bugs in one report. One report, one bug, one title.
• Guesses written as facts. Put leads under "Suspected cause" and say why.
• Screenshots without the step they belong to.
• Secrets and personal data: session cookies, API keys, customer names. Strip cookies from HAR files. A shared link is public to anyone who has it.

See also: agent handoff document, share an implementation plan and the REST API.

FAQ