chore: improve issue and PR templates with industry best practices (#1088)

Bug report template: - Add OS, Node.js version, shell, and install method fields - Add all 6 supported runtimes (+ Multiple option) - Add frequency and severity/impact dropdowns - Add config.json, STATE.md, and settings.json retrieval instructions - Add PII warnings on every field that could leak sensitive data - Recommend presidio-anonymizer and scrub for log anonymization - Add diagnostic commands for debugging install issues - Add mandatory PII review checklist checkbox Feature request template: - Add scope dropdown (core workflow, planning, context, runtime, etc.) - Add runtime multi-select checkboxes New templates: - Documentation issue template (incorrect, missing, unclear, outdated) - config.yml to disable blank issues and link Discord/Discussions PR template: - Add linked issue reference (Closes #) - Add How section for approach description - Add runtime testing checklist (all 5 runtimes + N/A) - Add template/reference update check - Add test pass check - Add screenshots/recordings section
2026-03-16 10:54:52 -04:00
parent 9d7001a6b7
commit 1e46e820d6
5 changed files with 309 additions and 16 deletions
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -1,59 +1,232 @@
 ---
 name: Bug Report
 description: Report something that is not working correctly
-labels: ["bug"]
+labels: ["bug", "needs-triage"]
 body:
  - type: markdown
    attributes:
      value: |
-        Thanks for taking the time to report a bug. Please fill out the sections below.
+        Thanks for taking the time to report a bug. The more detail you provide, the faster we can fix it.
+
+        > **⚠️ Privacy Notice:** Some fields below ask for logs or config files that may contain **personally identifiable information (PII)** such as file paths with your username, API keys, project names, or system details. Before pasting any output, please:
+        > 1. Review it for sensitive data
+        > 2. Redact usernames, paths, and API keys (e.g., replace `/Users/yourname/` with `/Users/REDACTED/`)
+        > 3. Or run your logs through an anonymizer — we recommend **[presidio-anonymizer](https://microsoft.github.io/presidio/)** (open-source, local-only) or **[scrub](https://github.com/dssg/scrub)** before pasting
+
  - type: input
    id: version
    attributes:
      label: GSD Version
-      description: "Run: npm list -g get-shit-done-cc"
+      description: "Run: `npm list -g get-shit-done-cc` or check `npx get-shit-done-cc --version`"
      placeholder: "e.g., 1.18.0"
    validations:
      required: true
+
  - type: dropdown
    id: runtime
    attributes:
      label: Runtime
+      description: Which AI coding tool are you using GSD with?
      options:
        - Claude Code
        - Gemini CLI
        - OpenCode
+        - Codex
+        - Copilot
+        - Antigravity
+        - Multiple (specify in description)
    validations:
      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating System
+      options:
+        - macOS
+        - Windows
+        - Linux (Ubuntu/Debian)
+        - Linux (Fedora/RHEL)
+        - Linux (Arch)
+        - Linux (Other)
+        - WSL
+    validations:
+      required: true
+
+  - type: input
+    id: node_version
+    attributes:
+      label: Node.js Version
+      description: "Run: `node --version`"
+      placeholder: "e.g., v20.11.0"
+    validations:
+      required: true
+
+  - type: input
+    id: shell
+    attributes:
+      label: Shell
+      description: "Run: `echo $SHELL` (macOS/Linux) or `echo %COMSPEC%` (Windows)"
+      placeholder: "e.g., /bin/zsh, /bin/bash, PowerShell 7"
+    validations:
+      required: false
+
+  - type: dropdown
+    id: install_method
+    attributes:
+      label: Installation Method
+      options:
+        - npx get-shit-done-cc@latest (fresh run)
+        - npm install -g get-shit-done-cc
+        - Updated from a previous version
+    validations:
+      required: true
+
  - type: textarea
    id: description
    attributes:
      label: What happened?
-      description: Describe what went wrong
+      description: Describe what went wrong. Be specific about which GSD command you were running.
+      placeholder: |
+        When I ran `/gsd:plan`, the system...
    validations:
      required: true
+
  - type: textarea
    id: expected
    attributes:
      label: What did you expect?
-      description: Describe what you expected to happen
+      description: Describe what you expected to happen instead.
    validations:
      required: true
+
  - type: textarea
    id: reproduce
    attributes:
      label: Steps to reproduce
-      description: How can we reproduce this?
+      description: |
+        Exact steps to reproduce the issue. Include the GSD command used.
      placeholder: |
-        1. Run /gsd:...
-        2. ...
+        1. Install GSD with `npx get-shit-done-cc@latest`
+        2. Select runtime: Claude Code
+        3. Run `/gsd:init` with a new project
+        4. Run `/gsd:plan`
+        5. Error appears at step...
    validations:
      required: true
+
  - type: textarea
    id: logs
    attributes:
-      label: Relevant logs or error messages
-      description: Paste any error output (will be formatted as code)
+      label: Error output / logs
+      description: |
+        Paste any error messages from the terminal. This will be rendered as code.
+
+        **⚠️ PII Warning:** Terminal output often contains your system username in file paths (e.g., `/Users/yourname/.claude/...`). Please redact before pasting.
      render: shell
    validations:
      required: false
+
+  - type: textarea
+    id: config
+    attributes:
+      label: GSD Configuration
+      description: |
+        If the bug is related to planning, phases, or workflow behavior, paste your `.planning/config.json`.
+
+        **How to retrieve:** `cat .planning/config.json`
+
+        **⚠️ PII Warning:** This file may contain project-specific names. Redact if sensitive.
+      render: json
+    validations:
+      required: false
+
+  - type: textarea
+    id: state
+    attributes:
+      label: GSD State (if relevant)
+      description: |
+        If the bug involves incorrect state tracking or phase progression, include your `.planning/STATE.md`.
+
+        **How to retrieve:** `cat .planning/STATE.md`
+
+        **⚠️ PII Warning:** This file contains project names, phase descriptions, and timestamps. Redact any project names or details you don't want public.
+      render: markdown
+    validations:
+      required: false
+
+  - type: textarea
+    id: settings_json
+    attributes:
+      label: Runtime settings.json (if relevant)
+      description: |
+        If the bug involves hooks, statusline, or runtime integration, include your runtime's settings.json.
+
+        **How to retrieve:**
+        - Claude Code: `cat ~/.claude/settings.json`
+        - Gemini CLI: `cat ~/.gemini/settings.json`
+        - OpenCode: `cat ~/.config/opencode/opencode.json` or `opencode.jsonc`
+
+        **⚠️ PII Warning:** This file may contain API keys, tokens, or custom paths. **Remove all API keys and tokens before pasting.** We recommend running through [presidio-anonymizer](https://microsoft.github.io/presidio/) or manually redacting any line containing "key", "token", or "secret".
+      render: json
+    validations:
+      required: false
+
+  - type: dropdown
+    id: frequency
+    attributes:
+      label: How often does this happen?
+      options:
+        - Every time (100% reproducible)
+        - Most of the time
+        - Sometimes / intermittent
+        - Only happened once
+    validations:
+      required: true
+
+  - type: dropdown
+    id: severity
+    attributes:
+      label: Impact
+      description: How much does this affect your workflow?
+      options:
+        - Blocker — Cannot use GSD at all
+        - Major — Core feature is broken, no workaround
+        - Moderate — Feature is broken but I have a workaround
+        - Minor — Cosmetic or edge case
+    validations:
+      required: true
+
+  - type: textarea
+    id: workaround
+    attributes:
+      label: Workaround (if any)
+      description: Have you found any way to work around this issue?
+    validations:
+      required: false
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: |
+        Anything else — screenshots, screen recordings, related issues, or links.
+
+        **Useful diagnostics to include (if applicable):**
+        - `npm list -g get-shit-done-cc` — confirms installed version
+        - `ls -la ~/.claude/get-shit-done/` — confirms installation files (Claude Code)
+        - `cat ~/.claude/get-shit-done/gsd-file-manifest.json` — file manifest for debugging install issues
+        - `ls -la .planning/` — confirms planning directory state
+
+        **⚠️ PII Warning:** File listings and manifests contain your home directory path. Replace your username with `REDACTED`.
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: pii_check
+    attributes:
+      label: Privacy Checklist
+      description: Please confirm you've reviewed your submission for sensitive data.
+      options:
+        - label: I have reviewed all pasted output for PII (usernames, paths, API keys) and redacted where necessary
+          required: true
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Discord Community
+    url: https://discord.gg/gsd
+    about: Ask questions and get help from the community
+  - name: Discussions
+    url: https://github.com/gsd-build/get-shit-done/discussions
+    about: Share ideas or ask general questions
--- a/.github/ISSUE_TEMPLATE/docs_issue.yml
+++ b/.github/ISSUE_TEMPLATE/docs_issue.yml
@@ -0,0 +1,47 @@
+---
+name: Documentation Issue
+description: Report incorrect, missing, or unclear documentation
+labels: ["documentation"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Help us improve the docs. Point us to what's wrong or missing.
+
+  - type: dropdown
+    id: type
+    attributes:
+      label: Issue type
+      options:
+        - Incorrect information
+        - Missing documentation
+        - Unclear or confusing
+        - Outdated (no longer matches behavior)
+        - Typo or formatting
+    validations:
+      required: true
+
+  - type: input
+    id: location
+    attributes:
+      label: Where is the issue?
+      description: File path, URL, or section name
+      placeholder: "e.g., docs/USER-GUIDE.md, README.md#getting-started"
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: What's wrong?
+      description: Describe the documentation issue.
+    validations:
+      required: true
+
+  - type: textarea
+    id: suggestion
+    attributes:
+      label: Suggested fix
+      description: If you know what the correct information should be, include it here.
+    validations:
+      required: false
--- a/.github/ISSUE_TEMPLATE/feature_request.yml
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -6,21 +6,56 @@ body:
  - type: markdown
    attributes:
      value: |
-        Thanks for suggesting a feature\! Please describe what you would like to see.
+        Thanks for suggesting a feature! Please describe what you'd like to see.
+
  - type: textarea
    id: problem
    attributes:
      label: Problem or motivation
      description: What problem does this solve? Why do you want this?
+      placeholder: "I'm frustrated when..."
    validations:
      required: true
+
  - type: textarea
    id: solution
    attributes:
      label: Proposed solution
-      description: How do you think this should work?
+      description: How do you think this should work? Include example commands or workflows if possible.
+      placeholder: |
+        A new command `/gsd:example` that...
    validations:
      required: true
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Which area does this affect?
+      options:
+        - Core workflow (init, plan, build, verify)
+        - Planning system (phases, roadmap, state)
+        - Context management (context engineering, summaries)
+        - Runtime integration (hooks, statusline, settings)
+        - Installation / setup
+        - Documentation
+        - Other
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: runtimes
+    attributes:
+      label: Applicable runtimes
+      description: Which runtimes should this work with?
+      options:
+        - label: Claude Code
+        - label: Gemini CLI
+        - label: OpenCode
+        - label: Codex
+        - label: Copilot
+        - label: Antigravity
+        - label: All runtimes
+
  - type: textarea
    id: alternatives
    attributes:
@@ -28,10 +63,11 @@ body:
      description: Have you considered other approaches?
    validations:
      required: false
+
  - type: textarea
    id: context
    attributes:
      label: Additional context
-      description: Any other information, screenshots, or examples
+      description: Any other information, screenshots, or examples.
    validations:
      required: false
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -6,11 +6,32 @@

 <!-- One sentence: why is this change needed? -->

+Closes #<!-- issue number -->
+
+## How
+
+<!-- Brief description of the approach taken. Skip for trivial changes. -->
+
 ## Testing

- [ ] Tested on macOS
- [ ] Tested on Windows
- [ ] Tested on Linux
+### Platforms tested
+
+- [ ] macOS
+- [ ] Windows (including backslash path handling)
+- [ ] Linux
+
+### Runtimes tested
+
+- [ ] Claude Code
+- [ ] Gemini CLI
+- [ ] OpenCode
+- [ ] Codex
+- [ ] Copilot
+- [ ] N/A (not runtime-specific)
+
+### Test details
+
+<!-- How did you verify this works? Manual steps, automated tests, etc. -->

 ## Checklist

@@ -18,7 +39,15 @@
 - [ ] Updates CHANGELOG.md for user-facing changes
 - [ ] No unnecessary dependencies added
 - [ ] Works on Windows (backslash paths tested)
+- [ ] Templates/references updated if behavior changed
+- [ ] Existing tests pass (`npm test`)

 ## Breaking Changes

+<!-- List any breaking changes, or write "None" -->
+
 None
+
+## Screenshots / recordings
+
+<!-- If this is a visual change, add before/after screenshots. Delete this section if not applicable. -->