🐙 GitHub Issue Template Engineer

Issue Templates: Python HTTP Retry Library

Diagnosis

Problem: your single Markdown bug template provides zero structure, so reporters fill in whatever they remember. Result: 60% of bug reports require follow-up, questions clog the issue tracker, and feature requests have no use-case context. Your 2-3 hour weekly triage is mostly chasing missing information.

Highest-leverage fixes:

1. Move to Issue Forms (YAML). Structured fields force reproduction code into bug reports. Cuts the 60% missing-repro problem to ~15%.

2. Redirect questions to Discussions. A `config.yml` blank-issue policy + Discussions link drops 25% of issue volume immediately.

3. Use a 'minimal reproducible example' field with a code-block placeholder. Reporters fill it in because the field expects it.

Estimated triage time savings: from ~2.5 hours/week to ~1 hour/week (40-60% reduction). Plus quality improvement on issues that do come through.

Template Inventory

For your repo, build these 4 issue templates:

1. Bug Report — for production bugs in the library. Expected: ~10/week.

2. Feature Request — for new functionality. Expected: ~6/week.

3. Performance Issue — for performance regressions or scaling questions. Expected: ~1-2/week.

4. Documentation Improvement — for unclear/missing docs. Expected: ~2/week.

Redirect to GitHub Discussions:

• Questions ('how do I use X')
• Discussion / proposals (RFCs)
• Show & tell

Skip these templates (your traffic doesn't justify):

• Security disclosure (use a SECURITY.md instead — most reporters know to follow that)
• Custom-issue-type templates per submodule

YAML Files

Drop these in .github/ISSUE_TEMPLATE/:

`1-bug-report.yml`

name: Bug Report
description: Report a bug or unexpected behavior in the library
title: "[Bug]: "
labels: ["bug", "needs-triage"]
body:
  - type: markdown
    attributes:
      value: |
        Thanks for taking the time to file a bug! To help us reproduce + fix faster, please fill in all required fields.
        
        - Searching existing issues first saves everyone time: https://github.com/OWNER/REPO/issues?q=is%3Aissue
        - For usage questions ('how do I do X?'), please use [Discussions](https://github.com/OWNER/REPO/discussions/categories/q-a) instead.
  
  - type: checkboxes
    id: searched
    attributes:
      label: Pre-filing checklist
      options:
        - label: I have searched [existing issues](https://github.com/OWNER/REPO/issues?q=is%3Aissue) and this is not a duplicate.
          required: true
        - label: I have read the [troubleshooting docs](https://github.com/OWNER/REPO/blob/main/docs/troubleshooting.md).
          required: true
  
  - type: textarea
    id: description
    attributes:
      label: Bug description
      description: Clear, concise description of the bug.
      placeholder: 'When I do X, I expect Y, but I get Z.'
    validations:
      required: true
  
  - type: textarea
    id: reproduction
    attributes:
      label: Minimal reproducible example
      description: |
        Paste minimal Python code that reproduces the issue. Include imports, library version, and a complete runnable snippet.
        
        See https://stackoverflow.com/help/minimal-reproducible-example for guidance.
      render: python
      placeholder: |
        from your_library import retry_client
        
        # ... your minimal repro here
    validations:
      required: true
  
  - type: textarea
    id: expected
    attributes:
      label: Expected behavior
      description: What you expected to happen.
    validations:
      required: true
  
  - type: textarea
    id: actual
    attributes:
      label: Actual behavior
      description: What actually happens. Include error messages or tracebacks (paste in code block).
    validations:
      required: true
  
  - type: input
    id: library-version
    attributes:
      label: Library version
      description: 'Output of `pip show your-library` — version line.'
      placeholder: '0.14.2'
    validations:
      required: true
  
  - type: dropdown
    id: python-version
    attributes:
      label: Python version
      options:
        - 3.9.x
        - 3.10.x
        - 3.11.x
        - 3.12.x
        - 3.13.x
        - Other (specify in additional context)
    validations:
      required: true
  
  - type: dropdown
    id: os
    attributes:
      label: Operating System
      options:
        - Linux
        - macOS
        - Windows
        - Docker container (specify base in additional context)
    validations:
      required: true
  
  - type: textarea
    id: additional
    attributes:
      label: Additional context
      description: Anything else relevant — related libraries, network conditions, frequency of occurrence.
    validations:
      required: false

`2-feature-request.yml`

name: Feature Request
description: Suggest a new feature or improvement
title: "[Feature]: "
labels: ["enhancement", "needs-triage"]
body:
  - type: markdown
    attributes:
      value: |
        Thanks for suggesting a feature! Use cases drive prioritization — please share yours.
  
  - type: checkboxes
    id: searched
    attributes:
      label: Pre-filing checklist
      options:
        - label: I have searched [existing issues + discussions](https://github.com/OWNER/REPO/issues) and this is not a duplicate.
          required: true
  
  - type: textarea
    id: use-case
    attributes:
      label: What problem does this solve?
      description: |
        Describe the use case. We prioritize features by use-case quality, not by how cleverly we could implement them.
        
        Example: 'I'm building a service that calls 50+ APIs with different retry policies. Currently I have to configure each separately. I want a way to define retry profiles I can reuse.'
      placeholder: |
        I'm trying to do X. I currently have to do Y, which is awkward because Z.
    validations:
      required: true
  
  - type: textarea
    id: proposal
    attributes:
      label: Proposed solution (optional)
      description: |
        If you have a specific API or implementation in mind, describe it. If not, that's fine — we'll figure out the API.
    validations:
      required: false
  
  - type: textarea
    id: alternatives
    attributes:
      label: Alternatives considered
      description: How are you currently working around this? Why aren't existing options sufficient?
    validations:
      required: false
  
  - type: dropdown
    id: willing-to-implement
    attributes:
      label: Are you willing to implement this?
      options:
        - 'Yes, I can submit a PR'
        - 'Maybe, with guidance'
        - 'No, just suggesting'
      default: 2
    validations:
      required: true
  
  - type: textarea
    id: additional
    attributes:
      label: Additional context
    validations:
      required: false

`3-performance-issue.yml`

name: Performance Issue
description: Report a performance regression or scaling concern
title: "[Perf]: "
labels: ["performance", "needs-triage"]
body:
  - type: markdown
    attributes:
      value: |
        Performance issues are easier to investigate with concrete benchmark numbers. The more specific you can be, the faster we can confirm + fix.
  
  - type: textarea
    id: description
    attributes:
      label: Performance issue description
      placeholder: 'Operation X takes Y seconds; I expected ~Z.'
    validations:
      required: true
  
  - type: textarea
    id: benchmark
    attributes:
      label: Benchmark / measurement
      description: |
        Numbers please. Use timeit, pytest-benchmark, or simple time.perf_counter().
      render: python
      placeholder: |
        import time
        start = time.perf_counter()
        # the slow operation
        print(time.perf_counter() - start)
    validations:
      required: true
  
  - type: textarea
    id: scale
    attributes:
      label: Scale / context
      description: 'How many requests/second, how many concurrent operations, etc.'
    validations:
      required: true
  
  - type: input
    id: library-version
    attributes:
      label: Library version
    validations:
      required: true
  
  - type: input
    id: regression-from
    attributes:
      label: Regression from version (if applicable)
      description: 'If this used to be faster in an older version, which one?'
    validations:
      required: false

`4-documentation.yml`

name: Documentation Improvement
description: Report unclear, missing, or incorrect documentation
title: "[Docs]: "
labels: ["documentation", "good first issue"]
body:
  - type: markdown
    attributes:
      value: |
        Thanks for helping improve the docs! These issues are usually quick fixes and great first contributions.
  
  - type: input
    id: page
    attributes:
      label: Documentation page or section
      description: 'URL or path to the relevant page/section.'
    validations:
      required: true
  
  - type: textarea
    id: issue
    attributes:
      label: What's unclear, missing, or incorrect?
    validations:
      required: true
  
  - type: textarea
    id: suggestion
    attributes:
      label: Suggested improvement (optional)
    validations:
      required: false

config.yml

.github/ISSUE_TEMPLATE/config.yml:

blank_issues_enabled: false
contact_links:
  - name: 'Question / How-to'
    url: https://github.com/OWNER/REPO/discussions/categories/q-a
    about: |
      For 'how do I use X?' questions, please use Discussions. 
      Issues are for bugs and feature requests only.
  - name: 'Discussion / Proposal'
    url: https://github.com/OWNER/REPO/discussions/categories/ideas
    about: |
      Open-ended discussions about library direction, RFCs, etc.
  - name: 'Security disclosure'
    url: https://github.com/OWNER/REPO/blob/main/SECURITY.md
    about: |
      For security issues, please follow our responsible disclosure policy. Do NOT open a public issue.
  - name: 'Show & Tell'
    url: https://github.com/OWNER/REPO/discussions/categories/show-and-tell
    about: |
      Share what you've built with the library!

blank_issues_enabled: false is the killer setting. It forces reporters to choose a template. Combined with the contact_links, ~25% of issue volume (questions) gets redirected to Discussions automatically.

Auto-Triage Setup

Add .github/workflows/issue-triage.yml:

name: Issue Triage
on:
  issues:
    types: [opened]

jobs:
  add-to-triage-project:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/add-to-project@v1
        with:
          project-url: https://github.com/orgs/YOUR_ORG/projects/N
          github-token: ${{ secrets.PROJECT_TOKEN }}
  
  add-internal-label:
    runs-on: ubuntu-latest
    if: contains(fromJson('["member1", "member2", "member3"]'), github.actor)
    steps:
      - uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.addLabels({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              labels: ['from-team']
            })

This adds:

• All new issues to your Triage project automatically (you already do this manually)
• A from-team label when issue is filed by an internal team member (helps you filter external vs internal at a glance)

Maintenance Tips

Iterate templates based on what you ask in follow-ups:

If you find yourself repeatedly asking 'what's your network setup?' on bugs, add a network-setup field to the bug template. If a field is rarely filled in, remove it.

Quarterly template review (15 min):

• Look at last quarter's issues
• Note: which fields had useful info, which had blank/'idk', which prompted follow-up questions
• Adjust template (add field, remove field, change required vs optional)

When to add a new template type:

• You see 5+ issues of a new pattern that don't fit existing templates (e.g., security advisory questions, integration questions)
• The new pattern would benefit from different required fields than existing templates

When to remove a template:

• It receives <2 issues/quarter — overhead of choosing the template exceeds value
• The pattern has shifted to Discussions naturally

What NOT to Include

1. Severity dropdown ('P0/P1/P2'): external reporters always pick P0. Triage manually.

2. 'Estimated time to fix' field: reporter has no idea. Skip.

3. 'Are you willing to implement this' on bug template: discourages bug filing. Keep on feature requests only.

4. Custom-emoji response template: cute but doesn't help triage.

5. A 'company' field: privacy-violating for OSS, mostly irrelevant for triage.

Migration from Existing Templates

Week 1:

• Add the 4 new YAML templates alongside the existing Markdown one
• Add config.yml with blank_issues_enabled: false
• Test by filing a sample issue yourself; verify the form works

Week 2:

• Delete the old bug_report.md (it's now replaced by 1-bug-report.yml)
• Notify in your README + recent release notes that templates have changed

Week 3-4:

• Monitor: are people filing template-correctly? Are field values useful?
• Add the auto-triage Action workflow

Month 2+:

• Iterate fields based on Q1 of new-template usage

Key Takeaways

• Issue Forms (YAML) over Markdown templates is the single biggest change. Forces structured input from day one.
• blank_issues_enabled: false + contact_links to Discussions cuts 25% of low-quality issue volume immediately.
• 'Minimal reproducible example' as a required code-rendered field cuts the 'missing repro' follow-up rate from 60% to ~15%.
• 4 templates is the right number for your repo. More is overhead; fewer misses use cases.
• Auto-triage via GitHub Actions saves manual labeling. Keep it simple — auto-add to Triage project + auto-label internal-vs-external.
• Iterate quarterly based on what you ask in follow-ups. Templates are living documents.