From af764903e77e8e39dd51a208628a11f00e1cfb29 Mon Sep 17 00:00:00 2001
From: Rootiest <chris@rootiest.com>
Date: Mon, 31 Aug 2026 23:07:44 -0400
Subject: [PATCH] docs(contributing): add issue templates for bugs, features,
 and docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Issues had no template at all, so a report arrived in whatever shape the
reporter chose — most often without a fish version, a reproduction, or the
full error text, which is what actually stalls a bug.

Add three templates under .github/ISSUE_TEMPLATE/, beside the PR template
so the GitHub mirror offers the same set:

- **bug.yaml** — a Gitea issue form rather than markdown. Version, OS,
  area, reproduction, expected and actual behavior are required fields, so
  an unactionable report can't be submitted in the first place. The Area
  dropdown exists because contributors without push access can't set an
  Area/ label themselves.
- **feature.md** and **docs.md** — comment-guided markdown in the same
  house style as PULL_REQUEST_TEMPLATE.md, since what they ask for is
  open-ended prose. feature.md carries `## Acceptance criteria`, the
  issue-side counterpart to a PR's `## Verification`. docs.md insists on
  the docs/manual/** source rather than the generated page, which the next
  CI run would overwrite.
- **config.yaml** — keeps blank issues enabled for what the three don't
  cover, and links the contributing guide and the customization docs.

Each template pre-applies its Kind/ label. Document the set, the plain-
description title convention (an issue states a problem; the conventional
subject belongs on the PR that closes it), and the triage split in a new
CONTRIBUTING.md § Issues.
---
 .github/ISSUE_TEMPLATE/bug.yaml    | 143 +++++++++++++++++++++++++++++
 .github/ISSUE_TEMPLATE/config.yaml |  13 +++
 .github/ISSUE_TEMPLATE/docs.md     |  80 ++++++++++++++++
 .github/ISSUE_TEMPLATE/feature.md  | 111 ++++++++++++++++++++++
 CONTRIBUTING.md                    |  67 ++++++++++++++
 5 files changed, 414 insertions(+)
 create mode 100644 .github/ISSUE_TEMPLATE/bug.yaml
 create mode 100644 .github/ISSUE_TEMPLATE/config.yaml
 create mode 100644 .github/ISSUE_TEMPLATE/docs.md
 create mode 100644 .github/ISSUE_TEMPLATE/feature.md

diff --git a/.github/ISSUE_TEMPLATE/bug.yaml b/.github/ISSUE_TEMPLATE/bug.yaml
new file mode 100644
index 0000000..fe1fdde
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug.yaml
@@ -0,0 +1,143 @@
+name: Bug report
+about: Something in the config is broken or behaves unexpectedly
+labels:
+  - Kind/Bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for filing a bug.
+
+        **Title it as a plain description of the problem**, not as a
+        conventional-commit subject — `mv clobbers a symlink when the target
+        exists`, not `fix(mv): ...`. The commit format belongs on the PR that
+        fixes this; the `Kind/` and `Area/` labels carry type and scope here.
+
+        Before filing, please confirm the problem survives a fresh shell
+        (`exec fish`) — a stale function definition in a long-lived session is
+        the single most common false alarm.
+
+  - type: input
+    id: fish-version
+    attributes:
+      label: fish version
+      description: Output of `fish --version`. This config targets fish 4.x.
+      placeholder: fish, version 4.0.2
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      description: Distribution and version, or macOS release.
+      placeholder: Arch Linux (CachyOS), kernel 6.12.4
+    validations:
+      required: true
+
+  - type: input
+    id: terminal
+    attributes:
+      label: Terminal emulator
+      description: >-
+        Only matters for rendering, key bindings, and color problems. Leave it
+        blank if the bug has nothing to do with those.
+      placeholder: kitty 0.42.1
+    validations:
+      required: false
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      description: >-
+        Which part of the config is affected? Pick the closest match — a
+        maintainer translates this into the matching `Area/` label at triage,
+        since contributors without push access can't set labels themselves.
+        Choose "Not sure" rather than guessing.
+      options:
+        - Not sure
+        - Functions (functions/)
+        - Completions (completions/)
+        - Config and startup (config.fish, conf.d/)
+        - Docs (docs/manual/, man page, docs site)
+        - Tests (tests/)
+        - CI (.github/workflows/)
+        - Integrations (integrations/)
+        - Prompt and theme (themes/)
+        - Opinionated components (C1-C6 toggles)
+        - Scripts (scripts/)
+    validations:
+      required: true
+
+  - type: textarea
+    id: summary
+    attributes:
+      label: What's broken
+      description: One or two sentences. Name the function or file if you know it.
+      placeholder: >-
+        `mv` replaces an existing symlink instead of prompting, so the link
+        target is lost with no confirmation.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: >-
+        Exact commands, starting from a fresh shell, that someone else can
+        paste and run. Include any setup needed to reach the broken state.
+      render: fish
+      placeholder: |
+        exec fish
+        mkdir -p /tmp/repro; cd /tmp/repro
+        touch real; ln -s real link
+        mv real link
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What you thought those commands would do.
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: >-
+        What happened instead. Paste the complete output, including any error
+        text and stack traces — truncated errors are the usual reason a bug
+        report stalls in Status/Need More Info.
+      render: text
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: preflight
+    attributes:
+      label: Pre-flight
+      options:
+        - label: I searched the existing issues and this isn't already reported.
+          required: true
+        - label: I reproduced this in a fresh shell (`exec fish`), not a long-lived session.
+          required: true
+        - label: I ran `fish tests/run-tests.fish` and noted the result below (or in the output above).
+          required: false
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: >-
+        Anything else worth knowing: a private overlay in
+        `~/.config/.user-dots/fish/` that may be involved, opinionated
+        components you've disabled, the last commit where it worked. Never
+        paste credentials, tokens, or machine-specific paths you'd rather not
+        publish.
+    validations:
+      required: false
diff --git a/.github/ISSUE_TEMPLATE/config.yaml b/.github/ISSUE_TEMPLATE/config.yaml
new file mode 100644
index 0000000..de6c3ee
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yaml
@@ -0,0 +1,13 @@
+# Gitea reads this alongside the templates in this directory.
+# Blank issues stay enabled deliberately: the three templates cover bugs,
+# features, and docs, and anything else (a chore, a refactor, a question)
+# is better served by an empty box than by a template that doesn't fit.
+blank_issues_enabled: true
+
+contact_links:
+  - name: Contributing guide
+    url: https://git.rootiest.dev/rootiest/fish-config/src/branch/main/CONTRIBUTING.md
+    about: Branch naming, commit conventions, coding standards, and the label taxonomy.
+  - name: Customization and personal overrides
+    url: https://git.rootiest.dev/rootiest/fish-config/src/branch/main/docs/manual/07-customization.md
+    about: Want to change behavior on just your machine? Use your private overlay — no issue needed.
diff --git a/.github/ISSUE_TEMPLATE/docs.md b/.github/ISSUE_TEMPLATE/docs.md
new file mode 100644
index 0000000..e121953
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/docs.md
@@ -0,0 +1,80 @@
+---
+name: Documentation issue
+about: Something in the manual, man page, config-help, or docs site is wrong, missing, or unclear
+labels:
+  - Kind/Documentation
+---
+
+<!--
+  Title this as a plain description of the problem:
+
+      config-help shows literal backticks in the customization section
+
+  not `docs(help): ...`. See CONTRIBUTING.md § Labels.
+
+  Docs in this repo are GENERATED. docs/manual/** plus the doc-header
+  comments above each function are the single source of truth;
+  docs/fish-config.md and docs/fish-config.1 are build output and are never
+  hand-edited. So a fix always lands in the source, not in the page where you
+  saw the problem — the Location section below asks for both.
+
+  Delete these comments as you fill it in.
+-->
+
+## Location
+
+<!--
+  Where you saw it, and where it actually comes from.
+
+  - **Where you saw it** — the docs site URL, the `config-help <topic>` you
+    ran, `man fish-config`, or the README section.
+  - **Source file** — the docs/manual/** page, or the function whose
+    doc-header feeds it (e.g. `functions/mv.fish`). If you're not sure which,
+    say so and leave it to triage rather than guessing.
+
+  If the problem appears in one output but not the others — correct on the
+  site, broken in the pager — say which, since that usually points at the
+  rendering pass (docs/codespans.py) rather than the source text.
+-->
+
+## Problem
+
+<!--
+  What's wrong. Quote the current text so it can be found and compared.
+  Common shapes, if it helps you place yours:
+
+  - **Wrong** — documents behavior the code doesn't have.
+  - **Stale** — described a flag or path that has since changed.
+  - **Missing** — a function, flag, or setting with no entry at all. Note
+    that a function with no `# CATEGORY` header is omitted from the manual
+    deliberately, so "missing" may be an intentional opt-out.
+  - **Unclear** — accurate, but a reader can't act on it. Say what you
+    expected to learn and what you concluded instead.
+  - **Renders wrong** — a broken code span, a mangled table, a bad anchor.
+-->
+
+## Suggested fix
+
+<!--
+  Proposed wording or structure, if you have one — a diff-shaped
+  before/after is ideal, but a rough sketch is welcome too. "I don't know
+  what it should say, only that this confused me" is a legitimate and useful
+  report; keep the heading and say that.
+
+  Two constraints on any text under docs/manual/, both enforced by
+  docs/verify-manual.py:
+
+  - No backticks inside an indented block.
+  - No backtick span wrapped across a line break.
+
+  Doc-headers in .fish files take no backticks at all — docs/codespans.py
+  adds code spans when it renders. See CONTRIBUTING.md § Documentation
+  Pipeline.
+-->
+
+## Notes
+
+<!--
+  Anything else — related issues (`Refs #42`), the commit that introduced the
+  problem, other pages with the same mistake. Drop this heading if empty.
+-->
diff --git a/.github/ISSUE_TEMPLATE/feature.md b/.github/ISSUE_TEMPLATE/feature.md
new file mode 100644
index 0000000..7fe99ae
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature.md
@@ -0,0 +1,111 @@
+---
+name: Feature or enhancement request
+about: Propose new functionality, or an improvement to something that already exists
+labels:
+  - Kind/Feature
+---
+
+<!--
+  Title this as a plain description of what you want, NOT as a
+  conventional-commit subject:
+
+      A picker for switching themes without editing config.fish
+
+  not `feat(theme): add theme picker`. That format belongs on the PR that
+  implements this; here, the Kind/ and Area/ labels carry type and scope.
+  See CONTRIBUTING.md § Labels.
+
+  This template applies Kind/Feature. If you're proposing an improvement to
+  something that already exists rather than genuinely new functionality, say
+  so in the Summary — a maintainer will swap the label to Kind/Enhancement
+  at triage. Contributors without push access can't set labels directly.
+
+  Keep every heading below except Alternatives considered and Notes, which
+  you can drop if they'd be empty. Delete these comments as you go.
+-->
+
+## Summary
+
+<!--
+  What you want, in one or two sentences. Lead with the capability, not the
+  implementation — "a way to preview a theme before committing to it" rather
+  than "add a --preview flag to theme-set".
+-->
+
+## Problem
+
+<!--
+  What's awkward, slow, or impossible today. Be concrete about the situation
+  that led you here: the sequence of commands you run now, what you have to
+  remember, or what goes wrong. A proposal is only as good as the problem it
+  names, and this section is what a reviewer weighs the cost against.
+-->
+
+## Proposed behavior
+
+<!--
+  The concrete shape of the thing. Where they apply:
+
+  - The command or function name, and its flags.
+  - What it prints on success, and what it does on the error paths.
+  - What happens with no arguments, or with a missing dependency.
+  - Whether it's interactive, and what it falls back to when it isn't.
+
+  A short usage sketch in a ```fish block is worth several paragraphs.
+-->
+
+## Alternatives considered
+
+<!--
+  Other approaches you weighed and why you set them aside — including
+  "solve it in my own ~/.config/.user-dots/fish/local.fish instead", which is
+  the right answer for anything genuinely specific to one machine or one
+  person's taste. See CONTRIBUTING.md § Secrets & Machine-Specific Config.
+
+  Drop this heading if there were no real alternatives.
+-->
+
+## Scope
+
+<!--
+  Answer these — they determine how the change has to be built, and getting
+  them wrong late is expensive:
+
+  - Does this shadow a builtin or an existing command?
+  - Does it run at startup, or bind a key, or set an environment variable?
+  - Does it need a new external dependency, and what should happen when that
+    dependency is missing?
+  - Is it opinionated enough that users should be able to turn it off? If any
+    of the above is yes, it likely needs a `# COMPONENT` header and an
+    `__fish_config_op_enabled` guard — see CONTRIBUTING.md § Opinionated
+    Components.
+  - Does it need a manual entry (a `# CATEGORY` header), and under which of
+    the docs/manual/05-functions/ categories?
+-->
+
+## Acceptance criteria
+
+<!--
+  What must be true for this issue to close, as a checkbox list. This is the
+  issue-side counterpart to a PR's ## Verification: it's the shared
+  definition of done, agreed before the work starts rather than argued about
+  after.
+
+  - One observable outcome per line — behavior a reader could check, not
+    implementation steps.
+  - Cover the error and fallback paths, not just the happy one.
+  - Include the docs and tests the change will owe.
+
+  Leave the boxes unchecked; they get ticked as the work lands.
+-->
+
+- [ ] 
+- [ ] 
+
+## Notes
+
+<!--
+  Anything else: prior art in other shells or dotfiles, links to the relevant
+  upstream tool's docs, related issues (`Refs #42`). Drop this heading if
+  there's nothing to add.
+-->
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e36ddea..90a93e5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -9,6 +9,7 @@ treat it as a living document, not a final word.
 ## Table of Contents
 
 - [Getting Started](#getting-started)
+- [Issues](#issues)
 - [Branching & Pull Requests](#branching--pull-requests)
 - [Commit Conventions](#commit-conventions)
 - [Fish Coding Standards](#fish-coding-standards)
@@ -34,6 +35,72 @@ If you're touching anything under `docs/manual/`, you'll also want `pandoc`,
 (see [Documentation Pipeline](#documentation-pipeline)) — otherwise CI will
 catch problems on push.
 
+## Issues
+
+Issues live on the Gitea repo. Three templates cover the common cases, each
+pre-applying its `Kind/` label; blank issues stay enabled for everything else
+— a chore, a refactor, a question, a tracking issue.
+
+| Template | Format | Use it for | Applies |
+|---|---|---|---|
+| **Bug report** | web form | Something is broken or behaves unexpectedly | `Kind/Bug` |
+| **Feature or enhancement request** | markdown | New functionality, or an improvement to what exists | `Kind/Feature` |
+| **Documentation issue** | markdown | The manual, man page, `config-help`, or docs site is wrong, missing, or unclear | `Kind/Documentation` |
+
+They live in `.github/ISSUE_TEMPLATE/`, next to the PR template, so the
+GitHub mirror offers the same set. The bug report is a Gitea *issue form* —
+a real web form with required fields — because a bug report missing its
+version, reproduction, or full error text can't be acted on, and a form
+refuses to submit without them. The other two are markdown templates in the
+same comment-guided style as `.github/PULL_REQUEST_TEMPLATE.md`, since what
+they ask for is open-ended prose that structure would only get in the way of.
+
+### Issue titles
+
+**Issue titles are plain descriptions of the problem, not Conventional
+Commits subjects.**
+
+```text
+mv clobbers a symlink when the target exists            ← yes
+fix(mv): prompt before replacing an existing symlink    ← no
+```
+
+An issue states a problem; a commit states a change. The type and scope that
+`fix(mv):` would carry are already on the issue as its `Kind/` and `Area/`
+labels, and the conventional subject belongs on the PR that closes it, where
+it becomes the commit message. Writing the fix into the title also presumes
+one, which is the wrong end to start from for anything still being diagnosed.
+
+### What an issue owes
+
+- **A bug** needs a reproduction someone else can paste and run, starting
+  from a fresh shell, plus the complete error output. A stale function
+  definition in a long-lived session is the most common false alarm, so
+  confirm it survives `exec fish` first. `Status/Need More Info` is where
+  reports without a reproduction end up.
+- **A feature** needs `## Acceptance criteria` — the checkbox list of what
+  must be true for the issue to close. It is the issue-side counterpart to a
+  PR's `## Verification`: a definition of done agreed before the work starts
+  rather than argued about after, and the PR's checks usually grow out of it.
+- **A docs issue** needs to name the `docs/manual/**` source, not just the
+  page where the problem showed up. `docs/fish-config.md` and
+  `docs/fish-config.1` are generated, and a fix applied there is overwritten
+  by the next CI run — see [Documentation
+  Pipeline](#documentation-pipeline).
+
+### Triage
+
+Reporters aren't expected to label anything. Contributors without push access
+can't, and the templates apply the `Kind/` label by themselves; the rest is
+the maintainer's job when the issue is triaged — add the `Area/` label (the
+bug form's **Area** dropdown is how a reporter tells you, since no forge can
+map a form field to a label), set a `Priority/` if it isn't ordinary, and
+apply `Reviewed/Confirmed` once a bug actually reproduces. See
+[Labels](#labels).
+
+When a PR resolves an issue it closes it with a trailing `Closes #N` line —
+see [Pull request descriptions](#pull-request-descriptions).
+
 ## Branching & Pull Requests
 
 **If you don't have push access to this repo**, fork it and open your PR