Contributing¶

YazSes is built by a small group of people, most of whom arrived, did one useful thing, and were credited for it. One contribution is a real contribution — a doc fix, a config you already use, a microphone that worked, or a bug report with yazses doctor output.

This page is the short version for people arriving from the docs. The authoritative guide is CONTRIBUTING.md in the repository, and it is the one to trust if these ever disagree.

Start here¶

Issue #22 is the front door — everything open, grouped by what you enjoy, with every link checked.

No code required¶

These are genuinely useful and need no Python:

Those four at the top hold many contributors at once — one entry each, nothing to claim, nothing to wait for.

If you do want to write code¶

git clone https://github.com/MSKazemi/yazses
cd yazses
uv sync
uv run python -m pytest tests/ -v

sudo apt install -y build-essential python3-dev git   # Debian / Ubuntu
sudo dnf install -y gcc python3-devel git             # Fedora / RHEL
sudo pacman -S --needed base-devel git                # Arch

You do not need a microphone, a Whisper model, or a GPU. The test suite is fully offline, mocks the audio and model layers, and runs in about 30 seconds.

ruff and pytest are the gates that must be green; mypy is advisory. If you changed a CLI command, flag or config key, run uv run python scripts/gen-docs.py or the doc-sync test will fail.

What to expect¶

We would rather merge a small imperfect pull request and polish it afterwards than leave you waiting, and we aim to reply within a few days. Red CI on your first push is normal — say so and we will help you read it.

Every contributor is credited on the wall in the README, including for work with no commit behind it — design review, research and bug reports count, and a script checks nobody with merged work is missing.

The design record is public¶

You never have to guess why YazSes works the way it does. The whole engineering and scientific record lives in design/ and is Apache-2.0 like the code:

• ~150 Architecture Decision Records — one per real decision, with the context, the options and the consequence. If you are about to change behaviour, there is probably an ADR explaining why it is that way.
• Feature specs and the as-built architecture.
• The research corpus — 105 verified references, and the ten open questions we think are worth measuring next.

Writing an ADR is itself a welcome contribution — a well-argued decision record is worth more than a rushed implementation. Start with design/README.md.

One rule worth knowing before you add a citation: we never commit PDFs of other people's papers. They are downloaded for personal research use, and republishing them would violate the authors' copyright — so we publish the citation and our own summary. The pre-commit hook blocks *.pdf outright.

The rules that will not bend¶

Two commitments a contribution cannot change without a superseding decision record: nothing leaves the machine by default, and new features ship off by default so nothing changes someone's setup until they opt in. GOVERNANCE.md covers the rest, including how a module becomes yours to review.

Using an AI assistant is fine — increasingly normal — but the pull request is yours, so please read every line and confirm the tests pass rather than assuming. AGENTS.md gives your assistant the conventions and the two rules it is most likely to break.

Questions¶

Ask in Q&A discussions — run yazses doctor first and paste the output. Feature ideas go in Ideas where everyone can vote; bugs go in issues, with a reproducer.

No question is too small.