A good bug report template asks for four things before anything else: what happened, what the person expected
instead, the steps that make it happen, and the version and the browser or OS they were on. How often it happens comes
next, and logs and screenshots last. Below is one as a GitHub issue form you can copy, a config.yml that keeps feature
requests and questions out of your bug tracker, and what to do when the people who find bugs are customers without a
GitHub account.
What a bug report needs#
Most bug reports that can't be fixed miss the same things. A report is worth working on when it says:
- What happened, in the reporter's words: the error message, the wrong number, the button that did nothing.
- What they expected. Many "bugs" are a difference of opinion, and this line tells you which ones.
- Steps that reproduce it, from a fresh start. "Sometimes it breaks" becomes "open a project, rename it, press Back".
- The version and the environment: the app's version, the browser or OS, and anything unusual about their setup.
- How often: every time, sometimes, or once. A bug that happened once and never again is triaged differently.
- Evidence: a log, a stack trace, a screenshot or a short recording.
The form asks for them in that order. Everything but the evidence is required: not every bug leaves a log, or shows in a screenshot.
The template, as a GitHub issue form#
Issue forms are YAML files in .github/ISSUE_TEMPLATE. GitHub shows them as a form instead of a blank text box, and
writes each answer into the issue under its label. Save this as .github/ISSUE_TEMPLATE/1-bug-report.yml on your
default branch:
name: Bug report
description: Something doesn't work the way it should.
title: "[Bug]: "
labels: ["bug"]
body:
- type: markdown
attributes:
value: |
Thanks for reporting this. The steps to reproduce it matter most: with them, we can usually fix it.
- type: textarea
id: what-happened
attributes:
label: What happened?
description: The error message, the wrong result, or what did nothing.
placeholder: I renamed a project and pressed Back. The list still showed the old name until I reloaded.
validations:
required: true
- type: textarea
id: expected
attributes:
label: What did you expect instead?
validations:
required: true
- type: textarea
id: steps
attributes:
label: Steps to reproduce
description: From a fresh start, one step a line.
value: |
1.
2.
3.
validations:
required: true
- type: input
id: version
attributes:
label: Version
description: Shown under Settings → About.
placeholder: "2.4.1"
validations:
required: true
- type: input
id: environment
attributes:
label: Browser or OS
description: And anything unusual about your setup, such as an extension or a VPN.
placeholder: "Safari 19 on macOS 26"
validations:
required: true
- type: dropdown
id: frequency
attributes:
label: How often does it happen?
options:
- Every time
- Sometimes
- It happened once
validations:
required: true
- type: textarea
id: logs
attributes:
label: Logs
description: Paste any error output. It's formatted as code, so no backticks are needed.
render: shell
- type: upload
id: screenshots
attributes:
label: Screenshots or a recording
description: Optional, if they show the problem better than words.
- type: checkboxes
id: searched
attributes:
label: Before you send it
options:
- label: I searched the open issues and found none like this one.
required: trueWhat GitHub's documentation says about these fields, as of October 2026:
- Issue forms are in public preview, so the syntax may still change.
requiredonly works in public repositories. In a private one, every field can be left empty.renderturns a textarea into a code block, which is what you want for logs and stack traces.uploadis a field for files, such as screenshots, recordings or log archives.- A label must already exist, or it's left off the issue.
bugis one of the labels a new repository starts with. - Your organization's issue types work too. If it defines a "Bug" type,
type: bugbesidelabelssets it.
Fill it in from your app#
Each field's id also names it in the address of a new issue. A "Report a bug" link in your app can send people to
the form with their version already filled in:
https://github.com/your-org/your-app/issues/new?template=1-bug-report.yml&version=2.4.1 They can't get the version wrong if they never have to type it.
Bugs here, requests and questions elsewhere#
A bug tracker fills up with things that aren't bugs: "it would be nice if…", "how do I…". A config.yml in the same
folder decides what the template chooser offers:
blank_issues_enabled: false
contact_links:
- name: Request a feature
url: https://feedback.example.com
about: Ideas and requests go on our feedback board, where others can vote for them.
- name: Ask a question
url: https://example.com/support
about: For help using the product.With blank_issues_enabled: false, people without write access can only open issues through your forms. If requests
stay on GitHub too, add a second form for them: the feature request template is one
to copy, and the 1- prefix keeps the bug form first in the list.
When the people who find bugs aren't on GitHub#
An issue form works when your users have GitHub accounts. A customer who hits a bug inside your product won't create one to tell you. They write to support, or they leave.
A feedback board inside the app takes those reports where they happen. Give it a board called "Bugs", and put the same questions in the board's description: what happened, what you expected, the steps, and a screenshot. Customers write in their own words, and the people who hit the same bug vote for that report instead of writing it again. The votes tell you how many people it affects.
From there, with Swingback's sync Beta, a member creates the GitHub issue from the report, with a title and a text written for engineers. Swingback adds no name, email or company of the person who reported it: the issue's text is what the member confirms before it's created.
When the fix merges and the issue closes as completed, the report completes too, and everyone who reported, voted for or commented on it hears that it's fixed. On GitHub, the person who opened an issue sees it close. On a board, so do the twenty customers who hit the same bug and never opened anything.
GitHub and Linear in the docs has how an issue is created from a report, and what each state of the issue does to it. If you're weighing a board against issues altogether, GitHub issues for feature requests goes through when each is enough.
