Discussions-First GitHub Intake for Maintainers

A lot of what lands in an issue tracker isn't work. It's a question filed as a bug, a feature pitch that belongs in an Ideas thread, or an install problem with no version anywhere in the body. Each one gets read, relabeled, and pointed somewhere else, and none of that moves the backlog.

My answer is a discussions-first policy. Questions, ideas, and suspected bugs start in GitHub Discussions and get triaged in public. An issue gets opened once there's confirmed work to track, and not before.

It takes five pieces: issue chooser routing, a reserved issue template, discussion category forms, CONTRIBUTING.md, and a pinned rules thread. The forms have their own post, How to Write Effective GitHub Discussion Templates, with the YAML and the Ideas and Community Help examples. This one covers the policy and the wiring, including what happens when someone clicks New issue anyway.

A Simple Policy¶

Discussions are the front door. Issues are for confirmed, actionable work.

Write that in CONTRIBUTING.md, repeat it in a pinned discussion, and back it with templates so the UI matches the docs.

flowchart TD
  contributor[Contributor] --> chooser[Issue chooser]
  chooser -->|contact_link| discussions[Discussion forms]
  chooser -->|reserved.yml| reserved[Reserved issue]
  discussions --> triage[Triage thread]
  triage -->|confirmed| issue[Tracked issue]
  reserved -->|pending-close| closed[Closed without review]

Route the Issue Chooser to Discussions¶

.github/ISSUE_TEMPLATE/config.yml is the first file I touch. Disable blank issues and put Discussions first as a contact_link. See Configuring the GitHub Issue Template Chooser for the full config.yml schema.

For a discussions-first repo, the file can look like this:

---
blank_issues_enabled: false
contact_links:
  - name: Discussions
    url: https://github.com/tenthirtyam/example/discussions/new/choose
    about: The starting point for questions, assistance, and discussions about this project.

blank_issues_enabled: false removes the blank-issue escape hatch. Point the Discussions link at discussions/new/choose so people pick a category right away instead of landing on the forum's front page.

GitHub lists contact links below the issue templates, so you can't move Discussions to the top of the chooser. If you have more than one contact link, list Discussions first, and write its about text like it's the default path: questions, help, and early bug reports start here.

Use a Reserved Issue Template¶

Some contributors will still open New issue. Give them one template, for example reserved.yml.

It's not a bug form. The body sends them to Discussions. The only checkbox makes them acknowledge they read that. Auto-apply a label such as pending-close so automation or triage can close the issue without a review cycle.

---
name: Reserved
description: Use GitHub Discussions for questions, assistance, and discussions about this project.
labels: ["pending-close"]
body:
  - type: markdown
    attributes:
      value: |
        > [!IMPORTANT]
        > Don't open an issue.
        >
        > Use [GitHub Discussions](https://github.com/tenthirtyam/example/discussions/new/choose) for questions, assistance, and discussions about this project.
  - type: checkboxes
    attributes:
      label: Acknowledgement
      options:
        - label: By submitting this issue, I affirm that I neglected to read the message above and can expect this item to be closed without review.
          required: true

Automate pending-close¶

People will file reserved issues anyway, and each one still costs you a notification and a context switch. Closing the first few by hand is fine. By the third, you'll want automation. A small workflow closes any issue labeled pending-close on open, posts a redirect comment with your Discussions link, and exits without a review debate:

---
name: Close Reserved Issues

on:
  issues:
    types: [opened, labeled]

permissions:
  issues: write

jobs:
  close-reserved:
    if: contains(join(github.event.issue.labels.*.name, ','), 'pending-close')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
        with:
          script: |
            const issue_number = context.payload.issue.number;
            const discussions = `https://github.com/${context.repo.owner}/${context.repo.repo}/discussions/new/choose`;

            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number,
              body: [
                'Thanks for opening an issue. This repository uses GitHub Discussions for questions, help, and early reports.',
                '',
                `Please start here: ${discussions}`,
                '',
                'Issues are reserved for confirmed, actionable work after triage.'
              ].join('\n')
            });

            await github.rest.issues.update({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number,
              state: 'closed',
              state_reason: 'not_planned'
            });

Create the pending-close label in the repository before you ship reserved.yml. The workflow needs issues: write permission only. Adjust the comment body to match your categories and triage policy.

Triage Bugs in Discussions First¶

Questions and ideas fit the Ideas and Community Help forms from the discussion templates post. Suspected bugs need a heavier form in Discussions first: version, environment, reproduction, expected versus actual behavior.

Add a Triage category (or reuse Community Help with a dedicated template if you prefer fewer categories). Create .github/DISCUSSION_TEMPLATE/triage.yml when the category slug is triage:

---
title: "[Triage]: "
labels: ["needs-triage"]
body:
  - type: markdown
    attributes:
      value: |
        Use this category when something looks like a bug but you're not sure yet. Maintainers will triage the thread and may ask you to open a tracked issue if it's confirmed.

        Before posting, [search existing discussions](https://github.com/tenthirtyam/example/discussions) and [search existing issues](https://github.com/tenthirtyam/example/issues). Use reactions to up-vote existing reports instead of duplicating them.

        When posting, include the following information.
  - 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: true
  - type: dropdown
    id: environment
    attributes:
      label: Environment
      description: Where the problem occurs.
      options:
        - Linux
        - macOS
        - Windows
        - Other
    validations:
      required: true
  - type: textarea
    id: description
    attributes:
      label: Description
      description: What happened? Be specific enough that someone can investigate.
    validations:
      required: true
  - type: textarea
    id: configuration
    attributes:
      label: Configuration or Code Sample
      description: |
        Minimal example, workflow snippet, or link to a [GitHub Gist](https://gist.github.com/).
        Remove secrets and identifiable information.
      render: yaml
    validations:
      required: true
  - type: textarea
    id: debug
    attributes:
      label: Debug Output
      description: Link to a Gist for long output. Paste only the relevant excerpt here.
      render: text
    validations:
      required: false
  - type: textarea
    id: expected-behavior
    attributes:
      label: Expected Behavior
    validations:
      required: true
  - type: textarea
    id: actual-behavior
    attributes:
      label: Actual Behavior
    validations:
      required: true
  - type: textarea
    id: steps-to-reproduce
    attributes:
      label: Steps to Reproduce
    validations:
      required: true
  - type: textarea
    id: references
    attributes:
      label: References
      placeholder: |
        #GH-0000
    validations:
      required: false

labels: ["needs-triage"] makes the queue visible. Maintainers and community helpers can ask follow-ups, mark an answer, or confirm a defect. Only then do you open an issue with your normal bug.yml workflow, often filed by a maintainer with the discussion link in the body.

That flow keeps the issue tracker thin: verified bugs and accepted enhancements, not every confused install report on day one.

Say It in Your Contributing Guidelines¶

GitHub surfaces CONTRIBUTING.md when someone opens an issue or pull request. Chooser links help, but the file is where you say Issues aren't for general help.

## Questions and Help

Don't open an issue for questions, installation problems, or "how do I" requests.

Use [GitHub Discussions](https://github.com/tenthirtyam/example/discussions/new/choose) instead.
Pick the category that matches your post (Community Help, Ideas, or Triage for suspected bugs).

## Bugs and Feature Requests

Confirmed bugs and accepted enhancements are tracked as issues. Maintainers may open an issue for
you after a discussion is triaged. If you open an issue without that triage step, expect it to be
closed and redirected to Discussions.

Keep the wording in line with Writing Practical Contribution Guidelines for GitHub Repositories, and update this section and the templates together when the policy changes.

Pin the Rules Thread¶

Form preambles are easy to skip, and nobody browsing the forum reads your YAML. Put the longer rules in a discussion and pin it so it's the first thing people see.

Use General if the rules cover the whole forum, or Community Help if they're mostly about asking for help. Write out the expectations, pin it, and link it from the chooser about text and from CONTRIBUTING.md. A good pinned post usually covers:

• Search First: links to docs, existing discussions, and common duplicates.
• Category Choice: Community Help for questions, Ideas for proposals, Triage for suspected bugs.
• Reactions over Duplicates: up-vote or react instead of opening parallel threads.
• Signal over Noise: no "+1" comments; add new information or reproduction detail only.
• Issues are Downstream: the tracker is for confirmed work after triage, not first contact.

Example body (adjust links and categories for your repo):

# Discussion Rules

Welcome. This board is for questions, ideas, and troubleshooting before anything becomes a tracked issue.

Please read and follow these rules before you post:

1. **Search irst.** Check [the docs](https://github.com/tenthirtyam/example/tree/main/docs), existing discussions, and open issues. Your question may already be answered.
2. **Use the Right Category.** Community Help for questions, Ideas for feature proposals, and Triage when you suspect a bug but need confirmation.
3. **Up-vote Instead of Duplicating.** If a thread already covers your topic, react or up-vote it. Do not open a parallel thread with the same question.
4. **Add Detail.** Version, environment, what you tried, and a minimal reproduction help maintainers respond once instead of five times.
5. **Don't Use Issues for General Help.** The issue tracker is for confirmed, actionable work. Questions and early reports belong here.

Maintainers may ask you to refine a post, move a conversation, or open an issue after triage confirms a defect.

Thank you for keeping the forum useful for everyone.

Lock the pinned thread if you don't want meta-discussion on the rules themselves. Update it when categories or policy change so the pinned post and CONTRIBUTING.md stay aligned.

Build Order¶

1. Enable Discussions and categories (Ideas, Community Help, Triage).
2. Add discussion category forms (templates post).
3. Set config.yml contact_links and blank_issues_enabled: false.
4. Add reserved.yml as the only public issue template if you want a strict policy.
5. Publish CONTRIBUTING.md and pin the rules discussion.

You need the routing and the forms together. Without forms, the chooser just moves vague reports from Issues to Discussions. Without routing, New issue is still one click away. Set up both, let the workflow close the pending-close holdouts, and don't open a tracked issue until a triage thread has confirmed the bug.