Help shape Cadence

A useful contribution can be a clearer explanation, a reproducible bug, a better exercise or a small, tested change.

Start with a task

Use the issue tracker to describe a problem or propose a bounded improvement. For an exercise, explain the musical goal, what the learner does and what evidence the app can honestly collect.

Do not include copyrighted book scans, private compositions, keys or application data in a public report. Reproduce problems with an original example when possible.

Build and check

The repository contains the native SwiftUI app, pure music/learning logic, tests and this static site. Xcode and macOS are required for the app.

git clone https://github.com/cigrainger/cadence.git
cd cadence
./build.sh
./verify.sh --tests-only
python3 Scripts/check_repository.py
python3 Scripts/build_site.py

Read CONTRIBUTING.md for the full workflow, formatting, fixtures and review expectations.

Keep the boundaries clear

Musical rules and learning evidence belong in MusicCore. Native views handle presentation and explicit actions. Hardware, network requests and durable storage stay behind testable adapters. Reuse the existing score, review and audio models before creating new ones.

Document decisions and invariants, especially when a result counts as supported or independent. Add regression tests for behaviour changes, failed saves and untrusted imports where they matter.

Share improvements on the same terms

Code contributions use AGPL-3.0-or-later. Documentation and original artwork use CC BY-SA 4.0. Sign off commits under the Developer Certificate of Origin; there is no copyright-assignment CLA. Third-party additions need provenance, a license and a dependency-inventory update.

Areas where human testing matters

Different MIDI keyboards, guitar and singing conditions, VoiceOver, keyboard-only navigation and longer learning sessions need real users. Automated screenshots and virtual MIDI checks are useful, but they cannot establish musical feel or accessibility by themselves.