A bug report template you can copy

A bug report template is a fixed set of fields that forces the same information out of every report, in the same order, every time. Which template you need depends on who is filling it in: a customer needs three or four short fields, a QA engineer needs ten, and a public repository needs a form GitHub can render for you. Below are four you can copy today.

This page is one part of a larger guide. For the whole subject in one place, see feature request tools.

Which template should you use?

Match the template to who is writing it, not to how serious the bug is.

• Customer-facing. Short, plain language, no technical fields. Use this on a support form or in an email reply.
• Internal QA. Longer, assumes the writer knows the product's architecture and can name a build number.
• Crash-specific. Adds the fields that only matter when the app actually stopped running: a stack trace, a crash log, the last action before it happened.
• GitHub issue form. A YAML file that renders as a structured form in a public repository, so contributors and users fill in the same fields instead of a blank text box.

The reasoning behind why each field earns its place is in the companion piece, how to write a good bug report. This post is only the templates.

A minimal template for customers

Four fields, plain language, nothing that assumes technical knowledge.

What were you trying to do?


What happened instead?


Does it happen every time, or just once?


What device or browser are you using?

• What were you trying to do: the goal, not the click. This is what separates a bug from a wish.
• What happened instead: the actual outcome, described plainly, not a theory about the cause.
• Every time or once: tells the reader whether to expect a clean reproduction or a one-off.
• Device or browser: the one piece of environment information most customers can give without digging.

A fuller template for internal QA

Ten fields, written for a colleague who already knows the product.

Title:

Severity: [blocker / major / minor / cosmetic]

Build or version:

Environment: [OS, browser or app version, device]

Preconditions:

Steps to reproduce:
1.
2.
3.

Expected result:

Actual result:

Frequency: [always / intermittent / once]

Logs, stack trace, or attachments:

Related issues:

• Title: specific enough to search for later, not a restatement of the severity.
• Severity: the reader's first triage signal, set by the writer, not assumed.
• Build or version: the exact release the bug was found in, so a fix can be verified against it.
• Environment: every axis that a bug can hide behind: operating system, browser, device, app version.
• Preconditions: the state the system had to be in before the steps below would work at all.
• Steps to reproduce: the numbered path from a known starting point to the failure.
• Expected result: what should have happened at the end of those steps.
• Actual result: what happened instead, stated as an observation, not an opinion.
• Frequency: whether the reader should expect the bug on the first attempt or the tenth.
• Logs, stack trace, or attachments: the evidence that supports the steps above, never a replacement for them.
• Related issues: anything already filed that looks similar, so duplicates get merged instead of triaged twice.

A template for a crash

Crashes need a version of the QA template with the failure evidence promoted to the top, because a stack trace is usually the fastest way in.

Title: [app] crashes when [action]

Build or version:

Device and OS:

Steps immediately before the crash:
1.
2.
3.

Did the app crash completely, or did one screen freeze?

Crash log or stack trace:


Does it crash every time you repeat those steps?

Anything unusual about this session? [low battery, low storage, poor network, background app]

• Steps immediately before the crash: often more useful than a formal reproduction, because the writer may not know which step actually caused it.
• Complete crash or frozen screen: these have different causes and the wrong assumption sends a developer down the wrong path.
• Crash log or stack trace: the single most useful field in this template when it exists. Attach the whole thing, not a screenshot of the top line.
• Unusual session conditions: low storage, low battery, and poor network cause a disproportionate share of crashes that never reproduce on a developer's own machine.

What does a GitHub issue template look like?

GitHub renders a YAML file in .github/ISSUE_TEMPLATE/ as a structured form instead of a blank text box, so every reporter fills in the same fields. This is the shape for a bug report.

name: Bug report
description: File a bug report
title: "[Bug]: "
labels: ["bug", "triage"]
body:
  - type: textarea
    id: what-happened
    attributes:
      label: What happened?
      description: Tell us what you expected and what happened instead.
      placeholder: I expected X, but Y happened instead.
    validations:
      required: true
  - type: textarea
    id: reproduce
    attributes:
      label: Steps to reproduce
      description: A numbered list, starting from a known point.
      placeholder: |
        1.
        2.
        3.
    validations:
      required: true
  - type: dropdown
    id: frequency
    attributes:
      label: Does this happen every time?
      options:
        - Always
        - Sometimes
        - Only once
    validations:
      required: true
  - type: input
    id: version
    attributes:
      label: Version
      description: Which version were you running?
      placeholder: v1.2.3
    validations:
      required: true
  - type: textarea
    id: logs
    attributes:
      label: Relevant log output
      description: This is automatically formatted as code, no backticks needed.
      render: shell
    validations:
      required: false

• name and description: what a reporter sees when choosing which template to open.
• title: a prefix applied automatically, so every bug report starts the same way in the issue list.
• labels: applied the moment the issue is filed, before anyone triages it by hand.
• type: textarea and type: input: textarea for anything multi-line, input for a single short value like a version string.
• id: the field's internal name, used if the form's answers are ever read by automation.
• validations: required: blocks submission until the field is filled in, which is the one thing a plain text box cannot do. Every key above is defined in GitHub's own form schema.
• render: shell: formats the field as a code block automatically, so pasted logs do not need manual backticks.

Frequently asked questions