# Contributing

Thanks for wanting to make `say-it` better. The most valuable contributions are **new pronunciation entries with real citations**.

## Adding a pronunciation

Open a PR adding one row to `data/pronunciations.tsv`. The columns are:

```
word | ipa | respelling_us | alt_ipa | alt_respelling_us | source_url | source_label | category | confidence | notes
```

### Field rules

- **`word`** — the lookup key. Lookup is case-insensitive, but preserve the canonical capitalization (e.g. `kubectl`, `PostgreSQL`, `LaTeX`).
- **`ipa`** — General American IPA, with stress marks, slashes optional. Example: `/ˈkuːb kənˌtroʊl/`.
- **`respelling_us`** — English-like phonetic respelling that macOS `say` will pronounce acceptably. Examples: `koob control`, `jay son`, `engine X`. **Test it** before submitting (see below).
- **`alt_ipa`** / **`alt_respelling_us`** — `|`-separated alternatives, paired by index. Empty if no alternates.
- **`source_url`** — link to a page that documents the pronunciation. Prefer:
  - The project's own pronunciation page / FAQ (`gnu.org/gnu/pronunciation.html`, `etcd.io/docs/v3.5/faq/`, etc.).
  - Wikipedia with a `#Pronunciation` anchor.
  - A creator interview or conference talk with a **specific timestamp**.
  - Avoid: generic project home pages with no pronunciation info, random Stack Overflow threads, unverifiable claims.
  - **Leave empty rather than fabricate.**
- **`source_label`** — short human-readable label for the source. Examples: `GNU Project official`, `Wikipedia § Pronunciation`, `creator's keynote @ KubeCon 2024 (12:30)`.
- **`category`** — one of `project`, `product`, `cli-tool`, `tool`, `cs-term`, `acronym`, `abbreviation`.
- **`confidence`** — one of:
  - `creator-clarified` — the source URL contains a creator quote, official FAQ entry, or canonical documentation of the pronunciation.
  - `community-consensus` — the reading is widely used in the community but lacks a single citable creator source.
  - `contested` — multiple readings genuinely compete in dev usage.
- **`notes`** — short editorial context. Never spoken aloud.

### Verifying your respelling

Respellings ride macOS Samantha's letter-to-sound rules. The pronunciation that sounds right in your head may not be what the TTS produces. **Always test:**

```bash
./bin/say-it -o /tmp/test.aiff <your-word>
afplay /tmp/test.aiff
```

If it sounds wrong, iterate on the respelling. Common pitfalls:

- macOS `say` may interpret `giff` as `/dʒɪf/` (same as `jif`). Use `gif` for the hard-G reading.
- `say` does not parse IPA, Apple PHON markup, or SSML phoneme tags. Respelling is the only path that works.
- Watch out for short tokens that get spelled letter-by-letter (e.g. `tmux` raw becomes "T-M-U-X"). Use a respelling like `T mux` or `tee mucks`.

Run `tools/audit-listen.sh <word>` to generate an `.aiff` for your entry in `.audit-audio/` and listen with `afplay`.

### Editorial principles

- **Tech-only.** The dictionary's scope is project names, product names, programmer jargon, and acronyms. Everyday English vocabulary is out of scope — `say-it <word>` falls through to raw TTS for those.
- **General American only.** UK / AU / IE / ZA readings are not in scope.
- **Under-claim, don't over-claim.** When in doubt, mark `community-consensus` and leave the source URL empty. A future PR can upgrade with a real citation.

## Code changes

For changes to `bin/say-it`, the static site (`docs/`, generated by `tools/build-site.sh`), or the Claude Code skill (`skills/pronounce-word/SKILL.md`):

- Test locally on macOS. The CLI uses `say` and `[[slnc N]]`; both are macOS-only.
- Regenerate the static site with `tools/build-site.sh` after dictionary changes.
- Update `CHANGELOG.md` under `## Unreleased` with a short bullet.

## Roadmap and ideas

See [`IDEAS.md`](IDEAS.md) for the brainstormed roadmap. Pick anything that looks fun. Bigger ideas are welcome as proposal PRs that update `IDEAS.md` first, before implementation.

## Licensing

By submitting a PR you agree your contribution is licensed under MIT (the project license).
