GitHub Issue Forms Template (Bug, Feature, Question)

Issue Forms: [Repository name]

A ready-to-copy set of GitHub issue forms for an open-source or internal repository: a bug report form, a feature request form, a question form that steers support questions away from the tracker, and the template chooser configuration. Based on the GitHub documentation "Syntax for issue forms" and "Syntax for GitHub's form schema" (checked 30 October 2026; issue forms are in public preview and subject to change). Replace every [bracketed] value and every line marked Example. Worked examples use Brindlemark, a fictional open-source Markdown editor.

Document control

Revision history

1. Planning the forms

Security vulnerabilities never go through these forms. The chooser links to the private reporting route described in the Security Policy (dev/security-policy).

2. Syntax essentials

3. Bug report form

Save as .github/ISSUE_TEMPLATE/bug_report.yml.

name: Bug report
description: Report something that does not work as documented in a released version.
title: "[Bug]: "
labels: ["bug", "needs-triage"]
body:
  - type: markdown
    attributes:
      value: |
        Thanks for taking the time to report a problem. Please search open and closed issues first.
        Security vulnerabilities must not be reported here: see SECURITY.md for the private route.
  - type: checkboxes
    id: preflight
    attributes:
      label: Before you start
      options:
        - label: I searched existing issues and this is not a duplicate.
          required: true
        - label: I can reproduce this on the latest release.
          required: false
  - type: input
    id: version
    attributes:
      label: Version
      description: Shown under Help, About. Example 2.4.1
      placeholder: "2.4.1"
    validations:
      required: true
  - type: dropdown
    id: platform
    attributes:
      label: Platform
      multiple: true
      options:
        - Windows
        - macOS
        - Linux
        - Web browser
    validations:
      required: true
  - type: textarea
    id: steps
    attributes:
      label: Steps to reproduce
      description: Numbered steps from a fresh start. Attach a minimal sample file if you can.
      placeholder: |
        1. Open a new document
        2. Paste a table with a merged cell
        3. Switch to preview
    validations:
      required: true
  - type: textarea
    id: expected
    attributes:
      label: Expected behaviour
    validations:
      required: true
  - type: textarea
    id: actual
    attributes:
      label: Actual behaviour
    validations:
      required: true
  - type: textarea
    id: logs
    attributes:
      label: Relevant log output
      description: Remove personal data and tokens before pasting.
      render: shell
  - type: upload
    id: screenshots
    attributes:
      label: Screenshots or sample files
      description: Optional. Images or a small sample document that shows the problem.
    validations:
      required: false
      accept: ".png,.jpg,.gif,.txt,.zip"

4. Feature request form

Save as .github/ISSUE_TEMPLATE/feature_request.yml.

name: Feature request
description: Describe a problem the product does not solve today.
title: "[Feature]: "
labels: ["enhancement", "needs-triage"]
body:
  - type: checkboxes
    id: preflight
    attributes:
      label: Before you start
      options:
        - label: I searched existing issues and the roadmap, and this is not a duplicate.
          required: true
  - type: textarea
    id: problem
    attributes:
      label: Problem
      description: What are you trying to do that you cannot do today? Who is affected?
      placeholder: "I keep the same warning box in many documents and have to edit each copy by hand."
    validations:
      required: true
  - type: textarea
    id: workaround
    attributes:
      label: Current workaround
      description: What you do instead, and roughly what it costs you in time or effort.
  - type: textarea
    id: proposal
    attributes:
      label: Proposed solution (optional)
      description: Sketches or examples from other tools are welcome. Maintainers may solve the problem differently.
  - type: dropdown
    id: impact
    attributes:
      label: Impact for you
      options:
        - Nice to have
        - Would use regularly
        - Blocking my workflow
      default: 0
  - type: dropdown
    id: contribute
    attributes:
      label: Would you help build it?
      options:
        - Yes, code
        - Yes, testing and feedback
        - Not at the moment

5. Question form

Save as .github/ISSUE_TEMPLATE/question.yml.

name: Question
description: Ask a usage question that the documentation did not answer.
labels: ["question"]
body:
  - type: markdown
    attributes:
      value: |
        For open-ended discussion, please use the community forum linked in the template chooser.
  - type: textarea
    id: question
    attributes:
      label: Your question
    validations:
      required: true
  - type: textarea
    id: tried
    attributes:
      label: What you tried
      description: Links to the documentation pages you read and the steps you took.
    validations:
      required: true
  - type: input
    id: version
    attributes:
      label: Version
      placeholder: "2.4.1"

6. Template chooser configuration

Save as .github/ISSUE_TEMPLATE/config.yml.

blank_issues_enabled: false
contact_links:
  - name: Report a security vulnerability
    url: https://github.com/[owner]/[repository]/security/advisories/new
    about: Please report security issues privately, never in a public issue.
  - name: Community forum
    url: https://github.com/[owner]/[repository]/discussions
    about: Ask open-ended questions and share ideas with other users.

7. Writing good fields

Write the form in plain language for a reader who may not be a native English speaker, and keep the same field names across forms so that triage people learn one layout.

8. Rollout and maintenance

Standard and licence note

Based on the GitHub documentation pages "Syntax for issue forms", "Syntax for GitHub's form schema" and "Configuring issue templates for your repository" (docs.github.com, checked 30 October 2026). Issue forms are a public preview feature, so check the current pages before relying on a field type or key. Key names are given as GitHub documents them; the forms, questions and wording are original. GitHub is a trademark of its owner; this template is not affiliated with or endorsed by GitHub. Brindlemark is fictional. Template licence: MIT.