Streamlining Discussions With Category Forms

GitHub has introduced Category Forms for Discussions, a feature that lets maintainers create structured templates for each discussion category. When users start a new discussion, the form guides them through providing all required information upfront, reducing the need for maintainers to chase down missing details during triage.

The benefit works both ways: contributors get a clear set of required fields and can submit a complete discussion without second-guessing what to include. Maintainers, in turn, spend less time on back-and-forth clarification and more time on actual responses.

How the Templates Work

The mechanism is analogous to Issue Forms. Maintainers create a discussion template as a YAML file under .github/DISCUSSION_TEMPLATE/. Each template corresponds 1:1 to a Discussion Category slug, so the template for the "Announcements" category lives at .github/DISCUSSION_TEMPLATE/announcements.yml.

Users don't need to learn a new workflow – the form renders automatically when they initiate a new discussion in a category that has a template. To see it from the contributor's side, GitHub's own community instance demonstrates the pattern: click "New Discussion" there to observe how categories parse into templated post structures.

Screenshot of the "new discussion" page in the GitHub community on GitHub.

Example Applications for Maintainers

The templates fit a wide range of repository workflows. Several illustrative scenarios show how Category Forms can be tailored:

  • A JavaScript library maintainer sets up a bug report template capturing the user's browser and operating system, a bug description, and steps to reproduce.
  • A design repository maintainer structures feedback forms with fields for the specific design under review, user feedback, and improvement suggestions.
  • An open source project maintainer designs a feature request template with fields for the proposed feature, its intended use case, and expected benefits.

Maintainers can start experimenting immediately by consulting the feature documentation and adopting templates into their community's discussion categories.