Issue Templates: Bug Report and Feature Request Templates

A vague bug report like 'it's broken' wastes everyone's time — the reporter's, and whoever has to follow up asking for the details that should have been included from the start. Issue templates solve this systematically, the same way PR description templates (a few lessons back) standardize pull request descriptions, guiding anyone opening a new issue toward providing the specific information needed to actually act on it.

Learning Objectives

Understand the purpose and structure of a bug report issue template.
Understand the purpose and structure of a feature request issue template.
Set up multiple issue templates using the .github/ISSUE_TEMPLATE directory.
Recognize GitHub's newer, structured 'issue forms' as an alternative to plain Markdown templates.

Key Terms to Know Before Setting Up Issue Templates

Issue template: A pre-defined structure that guides a contributor through providing specific, necessary information when opening a new issue.
Bug report template: An issue template specifically structured around reproducing and diagnosing a defect — typically requesting steps to reproduce, expected vs. actual behavior, and environment details.
Feature request template: An issue template specifically structured around proposing new functionality — typically requesting the problem being solved, the proposed solution, and any alternatives considered.
Issue forms: A newer, YAML-based GitHub feature for creating structured issue templates with distinct input fields (text boxes, dropdowns, checkboxes), rather than a single free-form Markdown template.

How GitHub Issue Templates Actually Work

A well-structured **bug report template** typically prompts for:

- **Description**: A brief summary of the bug.
- **Steps to reproduce**: An exact, numbered sequence someone else could follow to trigger the same bug — arguably the single most valuable piece of information in any bug report, since a bug that can't be reliably reproduced is often extremely difficult to diagnose or fix.
- **Expected behavior**: What should have happened.
- **Actual behavior**: What actually happened instead.
- **Environment details**: Relevant context like operating system, browser, or software version, since many bugs are environment-specific.

A well-structured **feature request template** typically prompts for a different set of information, since it's proposing something new rather than diagnosing something broken:

- **Problem or motivation**: What underlying problem or need is driving this request — understanding the 'why' often reveals whether the specific proposed solution is actually the best way to address it.
- **Proposed solution**: What the requester specifically envisions.
- **Alternatives considered**: Any other approaches the requester thought about and why they weren't preferred, which helps maintainers avoid re-litigating options that have already been considered and rejected.

Setting these up on a repository is done by adding Markdown files inside a `.github/ISSUE_TEMPLATE/` directory — for example, `.github/ISSUE_TEMPLATE/bug_report.md` and `.github/ISSUE_TEMPLATE/feature_request.md`. Each file typically begins with a small YAML 'front matter' block specifying its name and description as they'll appear in GitHub's template picker, followed by the actual Markdown structure that pre-populates the issue body:

```
---
name: Bug Report
about: Report a reproducible bug or unexpected behavior
title: '[BUG] '
labels: bug
---

## Description

## Steps to Reproduce
1.
2.
3.

## Expected Behavior

## Actual Behavior

## Environment
- OS:
- Version:
```

When a repository has more than one template file set up this way, GitHub presents a template picker when someone clicks 'New issue', letting them choose the appropriate structure (Bug Report, Feature Request, or a plain blank issue if that option remains enabled) before they start writing.

For more advanced needs, GitHub also supports **issue forms** — a newer, YAML-based format (`.yml` instead of `.md`) that creates genuinely structured input fields, such as required text boxes, dropdown selectors, and checkboxes, rather than a single block of pre-filled Markdown text a reporter could simply ignore or delete. Issue forms enforce that certain fields must be filled in before the issue can even be submitted, providing stronger guarantees of complete information than a plain Markdown template, at the cost of somewhat more setup complexity.

Issue Templates: Visual Walkthrough

Draw a 'New issue' button click leading to a template picker screen showing three cards: 'Bug Report — Report a reproducible bug', 'Feature Request — Suggest an idea for this project', 'Blank issue'. An arrow from 'Bug Report' leads to a pre-filled issue body showing headers: 'Description / Steps to Reproduce / Expected Behavior / Actual Behavior / Environment'. A parallel arrow from 'Feature Request' leads to a different pre-filled structure: 'Problem or Motivation / Proposed Solution / Alternatives Considered'. Below, show the underlying file structure: '.github/ISSUE_TEMPLATE/bug_report.md' and '.github/ISSUE_TEMPLATE/feature_request.md'.

Bug Report vs Feature Request Template: Key Differences

Aspect	Bug Report Template	Feature Request Template
Core purpose	Diagnose and reproduce a defect	Propose new functionality
Key sections	Steps to reproduce, expected vs. actual behavior, environment	Problem/motivation, proposed solution, alternatives considered
Most valuable field	Steps to reproduce (enables diagnosis)	Problem/motivation (reveals the underlying 'why')
Typical file location	.github/ISSUE_TEMPLATE/bug_report.md	.github/ISSUE_TEMPLATE/feature_request.md

Creating Issue Templates: File Structure and Examples

# File: .github/ISSUE_TEMPLATE/bug_report.md
---
name: Bug Report
about: Report a reproducible bug or unexpected behavior
title: '[BUG] '
labels: bug
---

## Description
A clear description of the bug.

## Steps to Reproduce
1.
2.
3.

## Expected Behavior

## Actual Behavior

## Environment
- OS:
- Browser/Version:

# --- File: .github/ISSUE_TEMPLATE/feature_request.md ---
---
name: Feature Request
about: Suggest a new idea or improvement for this project
title: '[FEATURE] '
labels: enhancement
---

## Problem or Motivation
What problem does this solve, or what need does it address?

## Proposed Solution

## Alternatives Considered

Breaking Down the Issue Template Example

Both files follow the same overall pattern: a YAML front-matter block (between the `---` markers) configuring the template's name, description, a default title prefix, and an automatically applied label, followed by the actual Markdown structure that becomes the issue's pre-filled body. The bug report template's default label (`bug`) and title prefix (`[BUG]`) and the feature request's (`enhancement` and `[FEATURE]`) demonstrate how templates can automatically apply some of the organizational metadata from the previous lesson — labels — right from the moment an issue is created, without requiring a maintainer to manually triage and label every new submission.

How Issue Templates Are Used on Real Open-Source Projects

Nearly every actively maintained open-source project on GitHub uses at minimum a bug report template, since it dramatically reduces the volume of vague, hard-to-act-on issue reports maintainers would otherwise need to follow up on.
Large, high-traffic open-source projects frequently use GitHub's more advanced issue forms specifically to enforce that critical fields (like a minimal reproduction case) cannot be skipped, given the sheer volume of incoming reports they need to triage.
Some projects intentionally disable the 'blank issue' option entirely, forcing every new issue through one of the structured templates, to maintain consistently high-quality incoming reports.
Product and engineering teams at companies often adapt these same open-source-inspired templates for internal issue tracking, even on private repositories, purely for the consistency and completeness benefits.

Issue Templates Interview Questions and Answers

Q1. What is the purpose of a bug report issue template, and what key information does it typically request?

It guides a reporter toward providing specific, actionable information rather than a vague description. Key sections typically include steps to reproduce (arguably the most valuable field, since it enables diagnosis), expected versus actual behavior, and environment details, since many bugs are context-specific.

Q2. How does a feature request template differ in structure from a bug report template?

Rather than focusing on reproducing a defect, it focuses on understanding a proposed addition: the underlying problem or motivation driving the request, the specific proposed solution, and any alternatives the requester already considered, which helps maintainers understand context without re-litigating already-rejected options.

Q3. How do you set up multiple issue templates on a GitHub repository, and what happens when a contributor clicks 'New issue'?

Add Markdown files inside a .github/ISSUE_TEMPLATE/ directory, each with a YAML front-matter block specifying its name and description. When more than one template exists, GitHub presents a template picker, letting the contributor choose the appropriate structure (or a blank issue, if still enabled) before writing.

Issue Templates Quiz: Test Your Understanding

1. What is generally considered the most valuable field in a bug report template?

The reporter's name
Steps to reproduce
The issue's creation date
The repository's star count

Answer: B. Steps to reproduce

Explanation: An exact, reproducible sequence of steps is often the single most valuable piece of information in a bug report, since a bug that can't be reliably reproduced is typically very difficult to diagnose or fix.

2. Where are GitHub issue template files typically stored in a repository?

.github/workflows/
.github/ISSUE_TEMPLATE/
/templates/issues/
/docs/templates/

Answer: B. .github/ISSUE_TEMPLATE/

Explanation: GitHub looks for issue template Markdown (or YAML issue form) files specifically inside a .github/ISSUE_TEMPLATE/ directory at the root of a repository.

3. What advantage do GitHub's newer 'issue forms' (YAML-based) offer over plain Markdown templates?

They automatically fix reported bugs
They can enforce that certain structured fields must be filled in before submission
They eliminate the need for labels
They only work on private repositories

Answer: B. They can enforce that certain structured fields must be filled in before submission

Explanation: Issue forms create genuinely structured input fields (text boxes, dropdowns, checkboxes) that can be marked required, providing stronger guarantees of complete information than a plain Markdown template a reporter could simply skip past.

Common Mistakes When Setting Up Issue Templates

Not including a 'steps to reproduce' section in a bug report template, making incoming bug reports significantly harder to diagnose and act on.
Using the same generic template for both bugs and feature requests, when each benefits from a distinctly different structure suited to its purpose.
Forgetting the YAML front-matter block, which is required for GitHub to correctly recognize and display the template in its picker.
Leaving the 'blank issue' option enabled without a clear reason on a high-traffic project, allowing vague, unstructured issues to bypass the templates entirely.

Issue Templates: Exam-Ready Quick Notes

Bug report template: description, steps to reproduce, expected vs. actual behavior, environment.
Feature request template: problem/motivation, proposed solution, alternatives considered.
Templates live in .github/ISSUE_TEMPLATE/ as Markdown files with a YAML front-matter block (name, about, title, labels).
Issue forms (YAML .yml format): a more advanced alternative with structured, enforceable required fields.

Issue Templates: Key Takeaways

Issue templates systematically improve the quality and completeness of incoming bug reports and feature requests.
Bug report and feature request templates are structured around fundamentally different goals — diagnosing a defect versus proposing something new — and should reflect that in their sections.
For projects needing stronger guarantees, GitHub's newer issue forms enforce required structured fields beyond what a plain Markdown template can guarantee.

Frequently Asked Questions About Issue Templates

Q1. What is a GitHub issue template?

It's a pre-defined structure that automatically pre-fills the body of a new issue with helpful prompts, guiding the reporter toward providing specific, necessary information rather than starting from a blank field.

Q2. What information should a bug report template ask for?

Typically a brief description, exact steps to reproduce the bug, what behavior was expected versus what actually happened, and relevant environment details like operating system or software version.

Q3. What information should a feature request template ask for?

Typically the underlying problem or motivation driving the request, the specific proposed solution, and any alternative approaches the requester already considered.

Q4. How do I set up issue templates on my GitHub repository?

Add Markdown files inside a .github/ISSUE_TEMPLATE/ directory, such as bug_report.md and feature_request.md, each starting with a YAML front-matter block specifying its name, description, default title, and labels.

Q5. What are GitHub issue forms, and how are they different from a regular Markdown template?

Issue forms are a newer, YAML-based (.yml) alternative that creates genuinely structured input fields — like required text boxes, dropdowns, and checkboxes — rather than a single editable block of Markdown text, providing stronger guarantees that certain information won't be skipped.

Summary

Issue templates guide contributors toward submitting complete, actionable issues rather than vague, hard-to-act-on reports. A bug report template typically requests a description, exact steps to reproduce (arguably its most valuable field), expected versus actual behavior, and environment details. A feature request template instead focuses on the underlying problem or motivation, a proposed solution, and alternatives already considered. Both are set up as Markdown files inside a `.github/ISSUE_TEMPLATE/` directory, each beginning with a YAML front-matter block specifying its name, description, default title, and labels — when multiple templates exist, GitHub presents a picker when a contributor clicks 'New issue'. For stronger guarantees of complete information, GitHub also supports newer, YAML-based issue forms, which create genuinely structured, optionally required input fields rather than a single block of editable Markdown text.