From 1f973d704cde4b9aa91199ab2d86245779cfc05c Mon Sep 17 00:00:00 2001 From: Jatin K Malik Date: Thu, 3 Sep 2026 03:19:48 +0000 Subject: [PATCH 1/2] Add CONTRIBUTING.md --- CONTRIBUTING.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 6 ++++++ 2 files changed, 57 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1ebde23 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,51 @@ +# Contributing + +Thanks for helping with VocaMac. Keep dictation on-device after the model is downloaded. Do not add a Voca cloud speech path. + +VocaMac is Beta, Apple Silicon only, macOS 14+. Intel Macs are not supported. + +Coding agents should also read [AGENTS.md](AGENTS.md). + +## Ways to help + +- Bugs and ideas: [GitHub issues](https://github.com/VocaHQ/vocamac/issues) +- Docs: `README.md`, `docs/`, and the Hugo site in `web/` +- App or test fixes against `main` +- Review PRs for privacy, insertion, and Apple Silicon regressions + +Look for `good first issue` when that label is in use. + + +## Development setup + +You need an Apple Silicon Mac on macOS 14+, plus Xcode 15+ or Swift 5.9+. + +```bash +git clone https://github.com/VocaHQ/vocamac.git +cd vocamac +make test +make build +make run +``` + +`make install` builds and copies the app to `/Applications`. `make help` lists the rest. + + +## Pull requests + +Open against main. Keep the diff focused. + +- Add or update tests for the behavior you change. +- Update README or docs/ when install, privacy, engines, or architecture change. +- Do not weaken on-device transcription, clipboard restore, or permissions without saying so in the PR. +- App CI runs on macos-15 with Xcode 26. Website CI runs when web/ changes. + +Maintainers can comment /build on a PR for a signed, notarized DMG. + +## Community + +Discord (https://discord.gg/t6muquAJbm) is the fastest place to talk with maintainers. Follow @vocahq on X. + +## License + +Contributions are licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). Opening a pull request means your contribution may be distributed under that license. diff --git a/README.md b/README.md index 97e5875..b479e8b 100644 --- a/README.md +++ b/README.md @@ -594,6 +594,12 @@ Release builds of VocaMac are **Developer ID signed and notarized** by Apple. Ac --- +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md). + +--- + ## 📄 License AGPL-3.0 License - see [LICENSE](LICENSE) for details. From d1776ac8350cf57e1ab5a4f9edab402d1d5d683e Mon Sep 17 00:00:00 2001 From: Jatin K Malik Date: Sun, 6 Sep 2026 00:33:17 +0000 Subject: [PATCH 2/2] Require Xcode in CONTRIBUTING setup make build and install call xcodebuild. A Swift-only install cannot produce VocaMac.app. --- CONTRIBUTING.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1ebde23..358195b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,7 +18,9 @@ Look for `good first issue` when that label is in use. ## Development setup -You need an Apple Silicon Mac on macOS 14+, plus Xcode 15+ or Swift 5.9+. +You need an Apple Silicon Mac on macOS 14+, plus Xcode 15+. + +`make build`, `make run`, and `make install` need Xcode (`xcodebuild`). A Swift 5.9+ toolchain alone is enough for some unit tests, not for building `VocaMac.app`. ```bash git clone https://github.com/VocaHQ/vocamac.git