fish-config/CONTRIBUTING.md

# Contributing to fish-config

This is a personal dotfiles repo, but it's run with practices meant to scale
to a team of contributors, not just one person's solo habits. This document
formalizes those practices so they live somewhere durable instead of only in
commit history and conversation memory. It will grow as the project does —
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)
- [Labels](#labels)
- [Commit Conventions](#commit-conventions)
- [Fish Coding Standards](#fish-coding-standards)
- [Opinionated Components](#opinionated-components)
- [Documentation Pipeline](#documentation-pipeline)
- [Testing](#testing)
- [Secrets & Machine-Specific Config](#secrets--machine-specific-config)
- [License](#license)

---

## Getting Started

You'll need [fish 4.x](https://fishshell.com/). Clone the repo and run the
test suite to confirm your environment is sane:

```fish
fish tests/run-tests.fish
```

If you're touching anything under `docs/manual/`, you'll also want `pandoc`,
`python3-yaml`, and Node 24+ to exercise the full doc-build pipeline locally
(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.

GitHub reads these same files on the mirror, and its schema differs from
Gitea's in two places, so both are pinned to the spelling that works on both
and each file says so in a comment: the chooser config must be `config.yml`
(GitHub ignores `config.yaml`), and `bug.yml` declares `description:` rather
than `about:` (GitHub requires it; Gitea accepts it as an alias). The two
markdown templates keep `about:`, which is correct for their format on both.

### 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
from a branch on your fork back to `main` here — everything below about
branch naming and commit hygiene still applies, it just happens on your
fork instead of a branch of this repo directly. The rest of this section
assumes you *do* have push access (maintainers, regular contributors).

- **Branch off `main` before starting work.** Don't accumulate uncommitted
  changes directly on `main`. (If you already started editing before
  branching, that's fine — create the branch now, before your first commit;
  branching doesn't touch the working tree.)
- **Merge target is `main`, via PR.** Contributors open the PR; the repo
  owner merges it. Don't merge your own PR.
- **Label every PR.** At minimum one `Kind/` and one `Area/`, same as an
  issue — see [Labels](#labels). If you can't set labels, say what the
  change is in the description and a maintainer applies them.
- **Don't merge until the `## Verification` checklist is fully checked.**
  Unchecked boxes are outstanding manual checks, not decoration. See
  [Pull request descriptions](#pull-request-descriptions) below.
- **Prefix in-progress PRs with `WIP:`.** If the branch still has code
  changes coming, open it as `WIP: type(scope): description`. Gitea
  recognizes the prefix, flags the PR as a draft, and refuses to merge it
  until the prefix is removed; drop it once the branch is complete.

  `WIP:` signals **more changes are coming** — not "done but unverified".
  A finished branch waiting on manual checks is an ordinary PR whose
  `## Verification` boxes aren't all ticked yet; that's already the merge
  gate above and doesn't need the prefix. The two are independent: a PR
  can be WIP with everything ticked, or complete with checks outstanding.
- **Keep feature branches focused.** If you stumble onto something unrelated
  to your current task while working (a pre-existing bug, a stray cleanup),
  don't fold it into the same commit or PR. Handle it with one of these,
  in order of preference:
  1. **Separate branch, separate PR, merged to `main` independently.** The
     default for anything that doesn't overlap the code your current branch
     touches. The two PRs review and merge independently, in either order.
  2. **Separate branch and PR, then sync `main` back into your feature
     branch** once it merges. Use this only when the unrelated fix actually
     touches the same file/function as your feature branch, or your feature
     branch depends on the corrected behavior to work or test correctly.
  3. **Commit directly to `main`.** Reserved for changes too small to
     justify a branch, or genuinely urgent fixes. **Always ask for explicit
     approval before doing this** — there's no standing exception, no matter
     how trivial the change looks.

### Pull request descriptions

Fill in `.github/PULL_REQUEST_TEMPLATE.md` — Gitea pre-loads it into the
description box when you open a PR. Every PR carries, in this order:

- **`## Summary`** — what changed and why, as a short paragraph, 2-5
  bullets, or both. Name concrete paths and identifiers in backticks, and
  explain the reasoning rather than restating the diff.
- **Optional `##` sections** — add what the change actually needs
  (`Root cause`, `Why`, `How it works`, `Behavior`, `Docs`, `Notes`,
  `Scope note`, `Opinionated guard (C1-C6)`), and skip them entirely for a
  straightforward change. A breaking change (title ending in `!` before
  the colon) must include `## ⚠️ Breaking Change` with the migration path.
- **`## Verification`** — always last. Every check this change needs, as a
  checkbox list, each with the exact command and its expected result.
  A **checked** box means verified, whether programmatically (test suite,
  linter, docs verifier, CI) or by hand; check those off before opening the
  PR. An **unchecked** box is an outstanding manual check the reviewer
  still has to perform — leave anything you couldn't verify yourself
  unchecked rather than dropping it.

  **This list is the merge gate: a PR isn't merged until every box is
  checked.** Only list checks that can actually be resolved — one nobody
  can run blocks the PR indefinitely. Put genuinely unverifiable caveats,
  assumptions, and known limitations in `## Notes` instead, where they
  inform the review without gating it.

When a PR resolves a tracked issue, close it with a trailing `Closes #42`
line at the end of `## Summary` — not at the very bottom of the body, since
`## Verification` is always last. `Fixes #N` and `Resolves #N` behave
identically. Repeat the keyword for each issue (`Closes #42, closes #43`); a
bare `#43` is only a link and won't close anything. To point at a related
issue that should stay open, drop the keyword and use `Refs #42`. Leave the
line out entirely when no issue is involved.

## Labels

**Every issue and every pull request carries exactly one `Kind/` label and at
least one `Area/` label.** Everything else is optional, and most of it is
applied by a maintainer at triage rather than by whoever opened the thing.

Labels are scoped: the `Group/Name` form renders as a two-tone chip in Gitea,
and for the three *exclusive* groups below Gitea enforces one-at-a-time by
swapping the old label out when you apply a new one.

### `Kind/` — what this is

Required, and by convention exactly one. Gitea doesn't enforce one-of here,
so pick the dominant character of the change instead of stacking two.

| Label | For |
|---|---|
| `Kind/Bug` | Something is not working |
| `Kind/Feature` | New functionality |
| `Kind/Enhancement` | Improves functionality that already exists |
| `Kind/Documentation` | Documentation changes |
| `Kind/Testing` | The test suite itself |
| `Kind/Refactor` | Restructures code without changing behavior |
| `Kind/Chore` | Tooling, dependencies, housekeeping |
| `Kind/Performance` | Makes existing behavior faster or lighter |
| `Kind/Security` | A security issue |

These deliberately mirror the Conventional Commits types in [Commit
Conventions](#commit-conventions), so a PR's label and its title agree:
`fix` → `Kind/Bug`, `feat` → `Kind/Feature` or `Kind/Enhancement`, `docs` →
`Kind/Documentation`, `test` → `Kind/Testing`, `refactor` →
`Kind/Refactor`, `chore` → `Kind/Chore`, `perf` → `Kind/Performance`.

### `Area/` — what it touches

Required, and non-exclusive on purpose: a change that adds a function, its
completions, and a manual entry gets all three.

| Label | Covers |
|---|---|
| `Area/Functions` | `functions/` |
| `Area/Completions` | `completions/` |
| `Area/Config` | `config.fish`, `conf.d/` — startup and environment |
| `Area/Docs` | `docs/manual/` and the generated manual, man page, and site |
| `Area/Tests` | `tests/` |
| `Area/CI` | `.github/workflows/` and repository automation |
| `Area/Integrations` | `integrations/` |
| `Area/Prompt & Theme` | `themes/` and prompt appearance |
| `Area/Components` | The opinionated-component system (C1-C6) |
| `Area/Scripts` | `scripts/` |

`Area/` is what makes the tracker searchable: it answers "what's still
outstanding in the docs pipeline?" in a way `Kind/` never can. Two edges
worth naming — `Area/Docs` covers the documentation *and its pipeline*, so
`README.md` and this file count even though they sit outside `docs/`; and
`Area/Components` is for the C1-C6 machinery itself, not for every function
that happens to carry a `# COMPONENT` header.

### `Compat/Breaking`

Applied to **any PR whose title carries `!` before the colon**, and to any
issue proposing a change that would. It travels with the `## ⚠️ Breaking
Change` section that such a PR must already include — see [Pull request
descriptions](#pull-request-descriptions).

### `Priority/` — exclusive, maintainer-applied

`Priority/Critical`, `Priority/High`, `Priority/Medium`, `Priority/Low`.

**No priority label means ordinary priority.** Labeling everything defeats
the point, so leave it off unless the item is genuinely more or less urgent
than the rest of the queue.

### `Reviewed/` — exclusive, maintainer-applied

`Reviewed/Confirmed` goes on a bug that has actually been reproduced —
that's the signal separating a report from a known defect.
`Reviewed/Duplicate`, `Reviewed/Invalid`, and `Reviewed/Won't Fix` accompany
closing an issue, always with a comment saying why; a close with only a
label on it is not an explanation.

### `Status/` — exclusive, maintainer-applied

`Status/Blocked`, `Status/Need More Info`, `Status/Abandoned`. These describe
the item's current state, so remove one as soon as it stops being true — a
stale `Status/Need More Info` on an issue that got its answer is worse than
no label, because it reads as still waiting.

### `good first issue` and `help wanted`

Invitations to contributors, applied by a maintainer. Both are deliberately
**unscoped**: they'd be a natural fit under `Status/`, but that group is
exclusive, and an issue is quite often both blocked on something *and* open
for someone to pick up. Keeping them outside the group lets them coexist
with a real status.

Use `good first issue` for work that is genuinely self-contained — a clear
acceptance criterion, one or two files, no need to understand the
opinionated-component system first.

### The GitHub mirror

The repo is mirrored to
[github.com/rootiest/fish-config](https://github.com/rootiest/fish-config),
and **the mirror carries the same labels, by the same names**. That isn't
cosmetic: GitHub reads the same `.github/ISSUE_TEMPLATE/` files, and a
`labels:` entry naming a label that doesn't exist on that side is silently
dropped rather than reported.

Mirroring copies files, not repository settings, so labels don't travel with
a push. **`.github/workflows/sync-labels.yml` closes that gap**: it runs
`scripts/sync-labels.py` on a daily schedule, and again whenever the script
itself changes, to make GitHub match Gitea. Manage labels here, in the Gitea
UI, and the mirror catches up within a day — or dispatch the workflow by
hand for it to happen now. Nothing needs doing on the GitHub side.

The sync creates what's missing and corrects color or description drift,
and it deletes an extra label on the mirror **only when no issue or PR there
carries it**; one that's in use is reported with its count and left for a
human to decide about. Run the script with `--dry-run` to see the plan
without changing anything, or `--self-test` to check its diff logic offline
— both are useful before editing it. Because labels are matched by name,
renaming one on Gitea reads as a delete plus a create: the new name appears
on the mirror, and the old one is pruned only if it's unused.

The workflow needs a GitHub token in this repo's Actions secrets as
`GH_MIRROR_TOKEN`, scoped to the mirror with **Issues: read and write**
(GitHub files labels under Issues) and **Pull requests: read** (so the
in-use check sees labels on PRs). The job fails with an explicit message if
it's missing rather than quietly doing nothing.

One behavioral difference to keep in mind: **GitHub has no exclusive
labels.** Gitea enforces one-at-a-time on `Priority/`, `Reviewed/`, and
`Status/` by swapping the old label out; on the mirror those are ordinary
labels and nothing stops two of a group coexisting, so there the one-of rule
holds by convention alone.

Issues and pull requests belong on the canonical Gitea repo — the template
chooser links there first, on both sides. The mirror's tracker stays open so
that a report which lands there anyway isn't lost, not because it's a second
supported front door.

## Commit Conventions

Commit subjects follow [Conventional Commits](https://www.conventionalcommits.org/):

```
type(scope): description
```

Types currently in use in this repo: `feat`, `fix`, `docs`, `test`, `chore`,
`perf`. The scope is usually the function, component, or subsystem touched
(e.g. `feat(help): ...`, `fix(scrub): ...`, `chore(docs): ...`). Look at
`git log` for recent examples before picking a type/scope for something
novel.

## Fish Coding Standards

### File header

Every hand-authored `.fish` file starts with:

```fish
# Copyright (C) 2026 Rootiest
# SPDX-License-Identifier: AGPL-3.0-or-later
```

(A few completion scripts adapted directly from a tool's own upstream
completions keep that tool's original attribution comment instead of this
header — match whichever convention the specific file already follows. New
files use the standard header above.)

### Public function documentation header

Every user-facing function gets a machine-parsed comment header directly
above its `function` line. This header is the single source of truth for
the generated manual (`docs/fish-config.md` / the man page / the docs
site) — see [Documentation Pipeline](#documentation-pipeline) for how it
gets consumed. The parser (`docs/manualtools.py`) recognizes these labels,
all optional except where noted:

| Label | Purpose |
|---|---|
| `CATEGORY` | **Required to appear in the manual at all** — see below. |
| `COMPONENT` | Only for functions gated by the [opinionated-component system](#opinionated-components). |
| `DEPENDENCIES` | Other functions this one calls that a reader may want to look up. |
| `SYNOPSIS` | One-line usage form. |
| `DESCRIPTION` | Prose description; can span multiple paragraphs. |
| `ARGUMENTS` | Flags/positional args, one per line. |
| `EXIT STATUS` | Exit codes and what they mean. |
| `RETURNS` | For functions used for their output/return value rather than exit status. |
| `EXAMPLE` | One or more realistic invocations. |
| `NOTES` | Anything else worth flagging (fallback behavior, caveats, gotchas). |

A full example (`functions/claude.fish`):

```fish
# Copyright (C) 2026 Rootiest
# SPDX-License-Identifier: AGPL-3.0-or-later

# CATEGORY
#   12-ai-and-developer-tools
#
# COMPONENT
#   aliases/dev-tools
#
# DEPENDENCIES
#   agents-init
#
# SYNOPSIS
#   claude [ARGS...]
#
# DESCRIPTION
#   Wrapper for the claude CLI that ensures the AGENTS/ sub-repository is
#   initialized and any agent-made changes are committed before launch.
#   ...
```

**`CATEGORY` is the opt-in gate for the manual:** a function with no
`# CATEGORY` line produces no manual entry at all — this is how bundled
plugin internals and prompt guts stay out of user-facing docs without an
exclusion list. `CATEGORY` must exactly match one of the existing
`docs/manual/05-functions/NN-*.md` stubs:

```
01-file-and-directory      08-terminal-management
02-navigation               09-clipboard
03-editors-and-viewers      10-network
04-git-and-version-control  11-pager-and-logging
05-package-management       12-ai-and-developer-tools
06-dependency-management    13-media-and-utilities
07-system-and-monitoring    14-miscellaneous
```

If your function genuinely doesn't fit any of these, add a new
`docs/manual/05-functions/NN-your-category.md` stub (with frontmatter
matching its siblings) rather than force-fitting it into an existing one.

### Private/internal helper functions

Functions named with a leading `_` (e.g. `_agents_init_ensure_gitignore`,
`__fish_config_op_enabled`) are excluded from the manual unconditionally,
regardless of whether they carry a `CATEGORY` line — so they generally don't
have one. They should still carry the standard file header, and a lighter
`SYNOPSIS`/`DESCRIPTION` comment is encouraged wherever the function's
purpose or calling convention isn't obvious from its body, matching the
convention already used across `__fish_config_op_*.fish` and similar files.

### Function declaration

Give every function a `--description`, since it's what shows up in `fish -c
'functions'`/completions and other introspection:

```fish
function my_function --description 'Short, imperative description'
```

### Colored `--help` output

Every function with a `-h`/`--help` flag uses this standardized color
palette (established across the codebase 2026-08-22):

```fish
set -l c_head  (set_color --bold cyan)   # section headers
set -l c_cmd   (set_color --bold)        # the command name itself (theme-adaptive)
set -l c_flag  (set_color yellow)        # flags
set -l c_arg   (set_color cyan)          # required-argument placeholders
set -l c_dim   (set_color brblack)       # optional-argument placeholders
set -l c_ok    (set_color green)         # success/positive status
set -l c_warn  (set_color yellow)        # warnings
set -l c_err   (set_color red)           # errors
set -l c_reset (set_color normal)
```

Not every function needs every variable — pull in only the ones your help
text actually uses. Structure the usage block as `Usage:`, then sections
for arguments/flags/examples as needed; see `functions/rand_string.fish` or
any recently-touched function for a full worked example.

## Opinionated Components

Some functionality in this config is classified into one of six toggleable
categories (C1–C6: aliases, autoexec, overrides, integrations, logging,
greeting) plus sub-categories, so users can disable pieces of it via
`config-settings` or universal variables. If you're adding something that
shadows a builtin, runs at startup, overrides a key binding/environment
variable, or otherwise falls under an existing category, tag it with a
`# COMPONENT` header (`<category>/<subcategory>`, e.g.
`overrides/key-bindings`) and guard it with `__fish_config_op_enabled`. See
the [README's Minimal Mode section](README.md#minimal-mode) for the full
category list and toggle semantics, and
`AGENTS/specs/2026-08-17-opinionated-component-subcategories-design.md` for
the underlying design. Most new functions are *not* opinionated components
— only tag something if it fits an existing category; this isn't something
to force.

## Documentation Pipeline

`docs/manual/` is the single source of truth for the user manual, man page,
and documentation site. **Never hand-edit `docs/fish-config.md` or
`docs/fish-config.1`** — they're generated by `docs/build-manual.py` from
`docs/manual/**` plus every function's doc-header (see above), verified by
`docs/verify-manual.py`, and auto-committed by CI on push to `main`
(`chore(docs): regenerate manual, man page, and component registry`).

If you're changing something under `docs/manual/` directly, or adding a
function whose `CATEGORY`/`COMPONENT` header should surface new content, you
can build and check it locally before pushing:

```fish
python3 docs/build-manual.py --concat -o docs/fish-config.md
python3 docs/verify-manual.py
```

CI runs the same verification and regenerates the site/man page — a broken
manual won't get published, but running it locally saves a round trip.

Write doc-headers as plain text — no backticks. `-a/--all`,
`__fish_config_op_aliases` and `~/.config/fish/config.fish` are typed
bare, because the header is also read as-is by `config-help` and by
anyone opening the file. `docs/codespans.py` adds the inline code spans
when it renders, so the SSOT never carries them; see
`docs/site/README.md` for which shapes it recognises. That pass runs for
every output — the site, the man page and `config-help` — so a token is
typeset the same way wherever it is read.

Two rules apply to backticks you write under `docs/manual/` as well:

- **Never inside an indented block.** A four-space block is verbatim in
  every renderer, so a backtick there is a literal character on the page
  rather than markup.
- **Never wrapped across a line break.** Markdown accepts a span split
  over two lines, but `config-help` pairs backticks one line at a time
  and would show the halves literally. Reflow the sentence instead.

`docs/verify-manual.py` enforces both.

## Testing

```fish
fish tests/run-tests.fish
```

Runs before every push and gates the documentation build in CI. Two phases:

1. **Syntax lint** — every tracked `.fish` file (`config.fish`, `functions/`,
   `conf.d/`, `completions/`, `integrations/`) is checked with `fish -n`.
2. **Sandboxed functional checks** — the config is copied into a throwaway
   `HOME`/`XDG_CONFIG_HOME` sandbox (never this checkout itself, since it
   doubles as a real `~/.config/fish`) and loaded as an isolated interactive
   session. `tests/functional.fish` then runs against foundational behavior:
   XDG/PATH/CDPATH setup, key bindings, abbreviations, core functions, the
   opinionated-component registry, and more.

To add a new functional check, add a `test_*` function to
`tests/functional.fish` — it's picked up automatically by
`functional_test_main`, no registration needed. Return 0 on pass, non-zero
on fail; print a short diagnostic on failure.

## Secrets & Machine-Specific Config

**Nothing containing credentials, tokens, personal identifiers, or a
specific machine's paths belongs in this repo — not even in a PR.** That
kind of thing lives in each user's own private overlay
(`~/.config/.user-dots/fish/secrets.fish` and `local.fish`), which is
git-ignored by design. If you're writing something that needs a secret or a
machine-specific path, source it from there rather than hardcoding it.
Everything else — general-purpose, reusable across machines — belongs in
the tracked repo as normal. See [README's Personalization
section](README.md#personalization) and
[`docs/manual/07-customization.md`](docs/manual/07-customization.md) for the
full mechanics.

## License

This project is licensed under AGPL-3.0-or-later (see `LICENSE`). Every new
hand-authored file needs the SPDX header shown in [File
header](#file-header) above.