# 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.

<!--
Guidance: How to use this template
- Copy each YAML block into its own file under `.github/ISSUE_TEMPLATE/` in the default branch. The file names in the headings are suggestions; the `name` key is what people see in the chooser.
- Create the labels first. GitHub does not create a label that a form names but the repository lacks; the issue is simply opened without it.
- Keep each form short. Every required field lowers the number of reports you receive, and the `required` validation only works in public repositories.
- The forms mirror the Markdown templates Bug Report (`dev/bug-report`) and Feature Request (`dev/feature-request`); keep the questions aligned when you change either. Point the question form at the channels in your Support file (`dev/support`).
-->

## Document control

<!-- Guidance: Treat the forms as code: one owner, reviewed changes, and a note in the revision history when a field is added or removed, because triage automation may depend on field IDs. -->

| Field | Value |
|---|---|
| Document ID | [ISSUE-FORMS-001] |
| Version | [1.0] |
| Owner | [@triage-lead] |
| Repository | [*Example:* `[owner]/brindlemark`] |
| Location | `.github/ISSUE_TEMPLATE/` on the default branch |
| Last updated | YYYY-MM-DD |
| Syntax checked against | GitHub Docs, Syntax for issue forms and Syntax for GitHub's form schema, YYYY-MM-DD |

### Revision history

| Version | Date | Author | Change |
|---|---|---|---|
| 1.0 | YYYY-MM-DD | [@name] | First set: bug, feature, question, chooser config |
| 1.1 | YYYY-MM-DD | [@name] | *Example:* Added `upload` field for screenshots to the bug form |

## 1. Planning the forms

<!-- Guidance: Decide what each form is for before writing YAML. Questions: what information do maintainers ask for most often in follow-up comments? Which reports belong somewhere else (security reports, support questions, discussions)? Pitfall: one long form for everything, which people abandon. -->

| Form | File | Purpose | Labels applied | Required fields |
|---|---|---|---|---|
| Bug report | `bug_report.yml` | A defect in a released version | `bug`, `needs-triage` | Version, steps to reproduce, expected and actual behaviour, duplicate check |
| Feature request | `feature_request.yml` | A problem the product does not solve today | `enhancement`, `needs-triage` | Problem statement, duplicate check |
| Question | `question.yml` | A short usage question that could not be answered by the docs | `question` | Question, what was tried |
| Chooser config | `config.yml` | Hides blank issues and links to support and security channels | Not applicable | Not applicable |

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

<!-- Guidance: Re-check these rules on the GitHub Docs page before each change; the feature is in public preview. -->

| Rule | Detail |
|---|---|
| Location | YAML files in `.github/ISSUE_TEMPLATE/`, merged to the default branch |
| Required top-level keys | `name`, `description`, `body` |
| Optional top-level keys | `title` (default issue title), `labels`, `assignees`, `projects`, `type` (organisation issue type) |
| Body element types | `markdown`, `input`, `textarea`, `dropdown`, `checkboxes`, `upload` |
| Element keys | `type` and `attributes` are required; `id` and `validations` are optional; `markdown` elements take no `id` |
| IDs | Letters, digits, `-` and `_` only, unique within the form; IDs let you prefill fields with URL query parameters |
| Dropdowns | `options` must be a non-empty list of distinct strings; with `default` set, do not offer "None" or "n/a" as options |
| Textarea `render` | Formats the answer as a code block in a named language, useful for logs |
| Uploads | Optional `accept` list of file extensions; GitHub applies size limits per file type |
| Validation | `required: true` is enforced in public repositories only |

## 3. Bug report form

<!-- Guidance: Ask for the minimum needed to reproduce: version, environment, steps, expected and actual result. Put the duplicate check first so people search before they write. -->

Save as `.github/ISSUE_TEMPLATE/bug_report.yml`.

```yaml
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

<!-- Guidance: Ask about the problem before the solution, and ask what the reporter does today. The cost of the workaround is the best evidence of value. -->

Save as `.github/ISSUE_TEMPLATE/feature_request.yml`.

```yaml
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

<!-- Guidance: Use this form only if questions really belong in the tracker. Many projects prefer to send them to discussions or a forum through `contact_links` in section 6 and skip this form. -->

Save as `.github/ISSUE_TEMPLATE/question.yml`.

```yaml
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

<!-- Guidance: `config.yml` controls the chooser people see when they open a new issue. With blank issues disabled, people with write access still see a blank option marked for maintainers. -->

Save as `.github/ISSUE_TEMPLATE/config.yml`.

```yaml
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

<!-- Guidance: A form is a conversation with someone who is already frustrated. Short labels, one question per field and an example in the placeholder do more than long instructions. -->

| Practice | Why it helps | *Example* |
|---|---|---|
| One question per field | Combined questions get half answers | Separate "Expected behaviour" and "Actual behaviour" fields |
| Show an example in `placeholder` | People copy the shape of the example | `2.4.1` for the version field |
| Explain where to find the answer in `description` | Saves a follow-up comment | "Shown under Help, About" |
| Use `render` for logs | Keeps long output readable and stops Markdown from mangling it | `render: shell` |
| Prefer dropdowns for closed answers | Gives consistent values that labels and searches can rely on | Platform list |
| Make few fields required | Required fields are the main reason people abandon a form | Only version, steps, expected and actual result |
| Warn about personal data | Logs and screenshots often contain names, paths or tokens | "Remove personal data and tokens before pasting" |

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

<!-- Guidance: Test the forms in a fork or a test repository before merging. Pitfall: renaming a field ID that a triage bot or saved search depends on. -->

| Step | Check |
|---|---|
| Validate YAML | Lint each file; open the form in a test repository and submit one issue of each type |
| Labels | Create `bug`, `enhancement`, `question` and `needs-triage` before merging |
| Links | Open every `contact_links` URL; replace `[owner]` and `[repository]` |
| Automation | Update triage bots or saved searches that read field IDs |
| Documentation | Mention the forms in CONTRIBUTING (`dev/contributing`) and the support channels in SUPPORT (`dev/support`) |
| Review | Every [6 months], read a sample of new issues and remove fields nobody fills well |

## 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.