# Contributing

## Code of conduct

Be kind. Accessibility-first means inclusive by default. See [the hackathon's CoC](https://musichackspace.org) for the baseline.

## Repo conventions

### Languages

- **TypeScript** for the web app (`apps/web/`)
- **Python 3.10+** for the audio service (`services/audio/`)
- **JSON** for pattern templates and onomatopoeia tables
- **YAML** for training data manifests

### Style

**TypeScript:**
- ESLint with `@typescript-eslint/recommended`
- Prettier for formatting
- No `any` unless absolutely necessary (and then comment why)
- Functional components, hooks, no class components
- Avoid `useEffect` for derived state — use `useMemo` or compute inline

**Python:**
- `ruff` for linting (replaces flake8, isort, etc.)
- `black` for formatting
- Type hints everywhere
- Pydantic for data models

### Naming

- Components: `PascalCase.tsx`
- Hooks: `useCamelCase.ts`
- Utilities: `camelCase.ts`
- Constants: `UPPER_SNAKE_CASE`
- Files match exports (one default export per file preferred)

### Git

**Commit format** (Conventional Commits):

```
<type>(<scope>): <description>

[optional body]

[optional footer]
```

Types:
- `feat` — new feature
- `fix` — bug fix
- `docs` — documentation only
- `style` — formatting, no code change
- `refactor` — code change that neither fixes a bug nor adds a feature
- `perf` — performance improvement
- `test` — adding or fixing tests
- `chore` — build, CI, tooling

Examples:
```
feat(parser): add onomatopoeia matcher with confidence scoring
fix(midi): correct GM drum map for china (should be 52, was 49)
docs(architecture): clarify Reaper integration is not a plugin
chore(ci): add axe-core to GitHub Actions
```

**Branch naming:**
- `feat/<short-description>`
- `fix/<short-description>`
- `docs/<short-description>`
- `chore/<short-description>`

Examples:
- `feat/voice-stt`
- `fix/midi-tempo-header`
- `docs/architecture-update`

### Pull requests

- One feature per PR
- PR description explains *what* and *why*
- Screenshots / screen recordings for UI changes
- Accessibility check included (NVDA test notes, axe-core results)
- All CI checks passing

### Accessibility requirements for every PR

If your PR touches the UI:

- [ ] Run axe-core locally (`npm run test:a11y`) — no AA violations
- [ ] Tab through the changed flow, verify focus order
- [ ] Test with NVDA (or document why you couldn't)
- [ ] All interactive elements have ARIA labels
- [ ] Color contrast meets WCAG AA (4.5:1 for normal text, 3:1 for large)
- [ ] No information conveyed by color alone

If your PR is docs-only or backend-only, skip these.

## Adding a new pattern template

1. Create `apps/web/data/patterns/<pattern-id>.json`
2. Follow the schema in [`03-data-model.md`](03-data-model.md#pattern-templates)
3. Test in the web app: `npm run dev`, load the pattern, generate MIDI, drag into Reaper
4. Verify the description reads naturally with a screenreader
5. Update the pattern list in [`03-data-model.md`](03-data-model.md#pattern-library--starting-list) if adding to the starting list

## Adding a new onomatopoeia

1. Edit `apps/web/data/onomatopoeia.json`
2. Add the entry with `patterns` (array of variants), `patternId`, and any defaults
3. Test the phonetic matcher: `npm run test:onomatopoeia`
4. Manually speak the variants, verify they map correctly

## Adding training data

1. Place audio in `data/training/oneshots/` or `data/training/loops/`
2. Preprocess: 44100 Hz mono, normalized to -14 LUFS
3. Add an entry to `data/training/manifest.yaml` with:
   - `id`, `path`, `category`, `tags`
   - `source`, `license`, `duration_seconds`
   - `bpm` (for loops only)
4. Run `python services/audio/training/preprocess.py` to regenerate the preprocessed versions
5. Verify the file plays correctly and the license is documented

## Accessibility testing protocol

Before opening a PR that touches UI:

1. **axe-core:** `npm run test:a11y` — must pass with no violations
2. **NVDA (Windows + Chrome/Firefox):**
   - Tab through the entire flow
   - Verify every state change is announced
   - Verify focus never disappears
   - Verify error states are announced
3. **VoiceOver (macOS + Safari):**
   - Repeat the NVDA flow
   - Especially test the grid navigation with VO + arrow keys
4. **Keyboard-only:**
   - Complete the entire demo flow without using the mouse
   - Verify every action has a keyboard equivalent
5. **High contrast:**
   - Enable Windows High Contrast Mode
   - Verify the UI is still usable
6. **200% zoom:**
   - Zoom the browser to 200%
   - Verify no content is cut off or unreachable

If any of these fail, the PR is not ready.

## Communication

- **Issues** — use GitHub Issues for bugs, feature requests, design questions
- **Discussions** — use GitHub Discussions for broader questions
- **Discord** — for real-time chat during the hackathon

## License

By contributing, you agree that your contributions will be licensed under the project's MIT license (code) or CC-BY (sample data where applicable).