docs/CONTRIBUTING.md

Contributing

Code of conduct

Be kind. Accessibility-first means inclusive by default. See the hackathon's CoC 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
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 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).