How to Write Effective GitHub Discussion Templates

I'm wiring up community intake for an upcoming open source project. Issue forms and a pull request template were the easy parts. Community discussions were what I hadn't nailed yet.

I wanted a public place for questions and early ideas without Issues turning into a pile of one-liners. I've set up GitHub Discussions on other repos before; this time I wanted the same structured intake issue forms already give you.

So I used discussion category forms: YAML on the same schema as issue templates, with required fields, defaults, and labels on create, tied to a category instead of an issue chooser. Questions stay in the forum. Work that needs a tracker still opens an issue.

If you've shipped issue templates before, the field types won't surprise you. What's different is the plumbing: .github/DISCUSSION_TEMPLATE/, one YAML file per category, and a filename that must match the category slug—not bug.yml copied from Issues.

Prerequisites¶

Categories define the shape of the conversation: open-ended discussion, question and answer, announcement, or poll. GitHub ships default categories such as General, Ideas, Q&A, Polls, and Announcements. You can rename them. This post uses Community Help instead of the default Q&A label, but the rule is the same: each category still needs a stable slug that your template filename must match. See Managing categories for discussions for how to create and edit them.

You can also route contributors away from Issues when Discussions is the better fit. In Configuring the GitHub Issue Template Chooser, contact_links send help requests to your Discussions page. Forms pick up from there: the same structured fields as issue forms, in the category someone already chose.

Where Files Live¶

Discussion category forms live in .github/DISCUSSION_TEMPLATE/ on your repository's default branch. Each file is a YAML form bound to one discussion category, not a chooser entry like issue templates use. Add one YAML file per category where you want a form. The examples below use placeholder tenthirtyam/example URLs; substitute your own org, repo, and discussion search links.

The Filename Rule¶

Issue template filenames are mostly free-form: bug.yml, enhancement.yml, and docs.yml appear in the chooser by their name and description fields. Discussion templates are different. The filename must match the slug of the discussion category.

If you add ideas.yml but the category slug is feature-requests, the form stays hidden until the filename matches. Slug first, then confirm Discussions is on.

What Contributors See¶

Issue forms show a chooser page: pick Bug, Enhancement, or Docs, then fill the form. Discussion forms don't use that pattern. A contributor picks a category first (Ideas, Community Help, and so on), then sees the form for that category only.

Don't copy bug.yml into DISCUSSION_TEMPLATE/ and expect it to work. Name the file after the category slug, not the issue template.

The Shape of a Discussion Form¶

Discussion forms share the body field schema with issue forms, but the top-level metadata is smaller.

Top-Level Keys¶

For array values, the same patterns apply:

labels: ["idea"]

labels: ["community-help"]

Field Types and body¶

The body key is where discussion forms stop being metadata and start becoming a workflow. Each entry in body: is a field or instruction block. GitHub requires at least one non-markdown field in body; a template that's only instructions won't submit.

Field types (markdown, input, textarea, dropdown, checkboxes, upload) are the same ones documented in How to Write Effective GitHub Issue Templates. Inside each body item, attributes controls presentation and validations controls whether the form can be submitted without a value.

Submitted content becomes Markdown in the discussion body. Contributors can still edit the discussion afterward, and others can reply, react, and (in question-and-answer categories such as Community Help) mark an answer.

For discussion-specific syntax, see Syntax for discussion category forms. For the shared field schema, see Syntax for GitHub's form schema.

Start With Two Forms¶

I usually start with two category forms:

That covers the two threads that otherwise show up as issues: "wouldn't it be nice if" and "how do I make this work."

Bug reports and scoped documentation fixes still belong in issue forms. For a discussions-first policy, add a Triage form before anything hits the tracker. See Discussions-First GitHub Intake for Maintainers.

Ideas Form¶

The Ideas category uses open-ended discussion format. Design the form to gather a clear description, a concrete use case, and optional supporting material without forcing contributors to open an issue prematurely.

Example:

---
title: "[Idea]: "
labels: ["idea"]
body:
  - type: markdown
    attributes:
      value: |
        Before starting a new idea, please [search existing discussions](https://github.com/tenthirtyam/example/discussions?discussions_q=category%3AIdeas) in this category, and use the [reaction](https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/) feature to up-vote ideas you support.

        When sharing an idea, please include the following information.
  - type: textarea
    id: description
    attributes:
      label: Description
      description: A written overview of the idea or proposed change.
    validations:
      required: true
  - type: textarea
    id: use-case
    attributes:
      label: Use Case(s)
      description: Describe the problem this idea would solve or the scenario where it helps.
    validations:
      required: true
  - type: textarea
    id: configuration
    attributes:
      label: Example Configuration
      description: |
        Optional example configuration, workflow snippet, or sketch of how the idea might look in practice.
        Learn more about [quoting code](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#quoting-code).
      render: yaml
    validations:
      required: false
  - type: textarea
    id: references
    attributes:
      label: References
      description: |
        Related discussions, issues, pull requests, or documentation.
        Learn about [referencing issues and pull requests](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#referencing-issues-and-pull-requests).
      placeholder: |
        #GH-0000
    validations:
      required: false

Put a search-and-upvote markdown block at the top, same idea as search-before-filing on a bug form.

title: "[Idea]: " gives discussions a consistent prefix in the list view. labels: ["idea"] pre-categorizes the thread so filters and automation have something to target.

Community Help Form¶

A Community Help category can use GitHub's question-and-answer format. Maintainers and community members can mark a comment as the answer, which surfaces the resolution at the top of the thread. Keep this form shorter than Ideas: the question, what was already tried, and optional diagnostics.

Example:

---
title: "[Help]: "
labels: ["community-help"]
body:
  - type: markdown
    attributes:
      value: |
        Before asking for help, please [search existing discussions](https://github.com/tenthirtyam/example/discussions?discussions_q=category%3ACommunity%20Help) in this category. Your question may already be answered.

        When asking for help, please include the following information.
  - type: textarea
    id: question
    attributes:
      label: Question
      description: What do you need help with? Be specific enough that someone can answer without guessing.
    validations:
      required: true
  - type: textarea
    id: context
    attributes:
      label: What You Tried
      description: |
        Include your environment, version, and any troubleshooting steps you already took.
        This helps responders avoid suggesting things you've already ruled out.
    validations:
      required: true
  - type: input
    id: version
    attributes:
      label: Version
      description: |
        The version you're using.
        Test with [the latest release](https://github.com/tenthirtyam/example/releases/latest) when you can.
      placeholder: e.g. 1.0.0
    validations:
      required: false
  - type: textarea
    id: logs
    attributes:
      label: Logs or Error Output
      description: |
        For long output, use a [GitHub Gist](https://gist.github.com/) and paste the link here.
      render: text
    validations:
      required: false
  - type: textarea
    id: references
    attributes:
      label: References
      description: Links to related discussions, issues, or documentation.
      placeholder: |
        #GH-0000
    validations:
      required: false

title: "[Help]: " mirrors the Ideas prefix pattern. Keep required fields focused on what you need to answer once; optional fields catch the cases where version or logs matter.

Habits Borrowed From Issue Forms¶

The search block at the top of body is the habit I copy first from How to Write Effective GitHub Issue Templates. Gist links for long logs in field descriptions travel over unchanged.

Make Formatting the Default¶

Use render: on textarea fields so GitHub wraps submitted content in fenced blocks automatically:

- type: textarea
  id: configuration
  attributes:
    label: Example Configuration
    render: yaml
  validations:
    required: false

For more on readability, see Please Format Your Code Blocks: GitHub Issue Etiquette. Discussion forms enforce the same defaults at submission time.

Search Before Posting¶

A markdown block at the top of body cuts duplicates better than anything else you'll add later. Link to a pre-filtered Discussions search for the category when you can.

Code of Conduct Acknowledgment¶

Issue forms often open with a required checkbox. Discussion forms support the same pattern:

- type: checkboxes
  id: terms
  attributes:
    label: Code of Conduct
    description: By participating, you agree to follow this project's [Code of Conduct](https://github.com/tenthirtyam/example/blob/main/CODE_OF_CONDUCT.md).
    options:
      - label: I agree to follow the Code of Conduct.
        required: true

Discussions Versus Issues¶

Discussion forms don't replace issue forms. They reduce the wrong submissions.

That split matches Writing an Effective Open Source Contributing Guide: questions in Discussions, actionable work in Issues. Templates on both sides put the routing in the UI, not just in prose.

Ship Ideas and Community Help first. Match each filename to its category slug, keep required fields short, and point the issue chooser at Discussions with contact_links when that fits your policy. Threads show up with a prefix, labels, and enough context that you're not replying "which version?" on post two.

For routing policy—reserved issues, automation, pinned rules—see Discussions-First GitHub Intake for Maintainers.