Contributing Start Here

Contributing — Start Here

We want your contribution, and we review fast. Docs fixes, a new voice command, platform polish, a translation — all of it counts, and small PRs are genuinely welcome. This page gets you from clone to merged.

1. Pick something to work on

• 🟢 Good first issues — scoped, beginner-friendly, often 10–30 minutes. Comment "I'll take this" and it's yours.
• 🆘 Help wanted — a bit bigger, still well-defined.
• 💡 Ideas — want to build something new? Open or upvote an Idea first so we can scope it together before you write code.

No need to ask permission for a small fix — just open the PR.

2. Set up your dev environment

YazSes is Python 3.11+ managed with uv.

git clone https://github.com/MSKazemi/yazses
cd yazses
uv sync                                   # install everything, incl. platform deps

uv run python -m pytest tests/ -v         # run the test suite (note: python -m pytest)
uv run ruff check src tests               # lint
uv run mypy src                           # type-check

Run the daemon straight from your checkout:

uv run yazses-daemon        # start the daemon
uv run yazses doctor        # confirm mic/hotkey/model/permissions
uv run yazses status        # query it over IPC

Linux note: hold-to-talk reads /dev/input, so your user must be in the input group (sudo usermod -aG input $USER, then log out and back in). yazses doctor tells you if this is the problem.

3. Make the change

• Keep PRs focused — one concern per PR. It gets reviewed and merged faster.
• Add a test for new behaviour. The suite is fast and the pure cores are designed to be testable without hardware — see How It Works.
• Match the surrounding code — comment density, naming, idioms.
• Update docs if user-facing — CLI changes touch docs/cli-reference.md; behaviour changes may touch README.md or docs/.

Where things live (quick reference)

I want to…	Look at
Fix dictation behaviour	src/yazses/core/daemon.py + audio/ / stt/ / postprocess/
Add a voice command	src/yazses/commands/grammar.py
Add OS / injection support	src/yazses/platform/base.py + a new platform/<os>/ or inject/ backend
Improve the CLI or doctor	src/yazses/cli.py, src/yazses/system/doctor.py
Docs only (great first PR)	docs/, README.md

Adding a new platform or injection backend

Implement the relevant Protocol interfaces in src/yazses/platform/base.py, add a test, and register your sys.platform value in platform/factory.py. The daemon and CLI require no other changes — that's the whole point of the abstraction.

4. Open the pull request

• Describe the why, not just the what.
• Confirm the test suite passes locally (CI will also run it on Linux × macOS × Windows).
• Link the issue it closes (Closes #123).

Then relax — we aim to give a first response within a day and to merge small, correct PRs quickly.

5. Recognition

Every contributor is credited. Merged work shows up in the repo's contributor graph and release notes. Contributing to YazSes is a clean, public, real-world open-source track record you can point to.

Ground rules

• Privacy is the product. Nothing in the dictation path may send audio off-device. Cloud-dependent ideas are fine to discuss, but on-device is the default and the tiebreaker.
• Be kind. We follow the Code of Conduct.
• License. Contributions are licensed under Apache 2.0 (see CONTRIBUTING.md).

Questions? Ask in Q&A — no question is too small.