Feature request template: a GitHub issue form you can copy

A good feature request template asks for the problem before the solution: what the person is trying to do, how they do it today, and how often it gets in their way. Their idea of a fix comes last, and is optional. Below is one as a GitHub issue form you can copy into your repository, then the same questions for a feedback board, where your customers ask without a GitHub account.

Why the problem comes first#

"Add a CSV export" is a solution. The problem behind it might be a weekly report for a manager, a migration to another tool, or a spreadsheet someone keeps by hand. Each calls for a different feature, and only one of them is an export. Requests that start with the problem:

• Can be compared. Five people asking for five different buttons may share one problem.
• Say how much it matters. "Every Monday, an hour" weighs more than "once, last year".
• Leave you room. You build what solves the problem, which may be smaller than what was asked.

So the template asks four things, in this order: the task, today's workaround, how often, and only then the idea.

The template, as a GitHub issue form#

Issue forms are YAML files in your repository's .github/ISSUE_TEMPLATE folder. GitHub shows them as a form with fields instead of a blank text box, and writes the answers into the issue under their labels. Save this as .github/ISSUE_TEMPLATE/feature-request.yml on your default branch:

name: Feature request
description: Ask for something the product doesn't do yet.
title: "[Request]: "
labels: ["enhancement"]
body:
  - type: markdown
    attributes:
      value: |
        Thanks for asking. Tell us about the problem first: a solution can come later, and is optional.
  - type: textarea
    id: problem
    attributes:
      label: What are you trying to do?
      description: The task, and what gets in the way today.
      placeholder: Every Monday I copy last week's tickets into a spreadsheet for my manager, and it takes an hour.
    validations:
      required: true
  - type: textarea
    id: workaround
    attributes:
      label: How do you do it today?
      description: A workaround, another tool, or not at all.
  - type: dropdown
    id: frequency
    attributes:
      label: How often does it come up?
      options:
        - Every day
        - Every week
        - Every month
        - Rarely
    validations:
      required: true
  - type: textarea
    id: idea
    attributes:
      label: What would solve it for you?
      description: Optional. Any idea helps, but the problem above matters most.
  - type: checkboxes
    id: searched
    attributes:
      label: Before you send it
      options:
        - label: I searched the open requests and found none like this one.
          required: true

A few things GitHub's documentation says about these files:

• Issue forms are in public preview, so their syntax may still change.
• required is enforced in public repositories only. In a private one, the fields are there but can be left empty.
• A label must already exist. enhancement is one of the labels a new repository starts with; one that doesn't exist is left off the issue.
• # starts a YAML comment. A Markdown heading in a markdown element's value goes in quotes, or under | as above.

To send people elsewhere for questions and support, add .github/ISSUE_TEMPLATE/config.yml beside it:

blank_issues_enabled: false
contact_links:
  - name: Questions and help
    url: https://example.com/support
    about: Ask here, not in an issue.

With blank_issues_enabled: false, people without write access to the repository can only open an issue through your templates.

The same questions on a board#

A form on GitHub reaches people with a GitHub account. When the people who ask are your customers, a feedback board takes their requests instead, and the questions move to two places:

• The board's description, which people read before they write: "Tell us what you are trying to do, how you do it today and how often it comes up. Your idea of a fix is welcome too."
• The similar requests shown while they type a title. They replace the "I searched" checkbox: a person sees the request that already exists, and votes for it instead of writing it again.

The answers then don't stay in a form. A request on a board gathers votes, the comments of the people who have the same problem, and who they are: their company, and what it's worth to you. That is the part an issue can't hold, and the reason many teams keep both, a board for asking and issues for building.

Reading the answers#

When requests arrive in this shape, triage gets quicker:

1. Group by problem, not by wording. Merge requests that share a task, whatever fix each proposes.
2. Weigh frequency and who asks. "Every day" from your largest customers outranks "rarely" from a free trial.
3. Answer with the problem's words. "You'll be able to send that Monday report without copying it" tells the person you understood, whatever you build.

In Swingback, a board's description is set under Boards, and the portal shows similar requests as people type; the portal's docs have the rest.