2026-09-01 03:36:03 +00:00
5 changed files with 414 additions and 0 deletions
@@ -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
@@ -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.
@@ -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.
+-->
@@ -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.
+-->
@@ -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