Contributing

How to propose changes to VoicEra.

Contributions are welcome. This page covers the workflow; Local setup covers getting the code running.

Before you start

• Open an issue first for anything substantial. A design discussion is cheaper than a rejected pull request.
• Read Repository layout so your change lands in the right package.
• Adding a provider or a telephony vendor? Follow Adding an AI provider or Adding a telephony provider — both are designed as extension points, so you should not need to touch shared code.

Setting up

git clone https://github.com/COSS-India/VoicEra.git
cd VoicEra
make application-up

make application-up wraps ./scripts/start-application-services.sh; make help lists every target.

There is no pip install -e . — pyproject.toml is an empty placeholder. Install per app:

pip install -r apps/api/requirements.txt
pip install -r apps/runtime/requirements.txt

Branching

Branch from dev, not main:

git checkout dev
git pull
git checkout -b your-change

Use a short descriptive name. Existing branches follow patterns like dev-<feature> and chore/<task>.

Commit messages

Match the existing history: a sentence-case imperative summary, no type prefix, no trailing period.

Add campaign CSV upload functionality and validation
Enhance call log patching functionality and introduce new endpoint
Standardise both STT models on /v1/realtime; detect MPS rather than assume it

Add a body when the reason is not obvious from the diff. Keep the summary under about 72 characters.

Code style

Rule	Value
Line length	100
Target Python	3.12 (model-server); the apps run on 3.11+
Type hints	Expected on new code; the codebase uses from __future__ import annotations
Docstrings	One line on modules and public functions

model-server/ruff.toml is the lint configuration for that tree. It deliberately excludes vendored upstream model code — restyling somebody else’s project turns every upstream sync into a merge conflict — but everything authored here is linted.

cd model-server && ruff check .

Match the surrounding code. The repository favours explicit registries over if/elif chains, Pydantic models at boundaries, and small modules over large ones.

Run the checks

There is no CI, so nothing runs these for you. Run them before opening a pull request:

python -m pytest apps/api/tests
python -m pytest apps/runtime/tests
python -m pytest apps/telephony/tests
python -m pytest apps/providers/tests
cd model-server && python -m pytest tests

The model-server suite needs no GPU. See Testing for what each suite protects.

Opening a pull request

Target dev. In the description:

• What changed and why.
• Which suites you ran, and their result.
• Anything you deliberately left out.
• For behaviour changes, how a reviewer can reproduce it.

Keep pull requests focused — one concern each. A refactor bundled with a feature is hard to review and harder to revert.

Documentation

Documentation lives in docs/ and is built with Mintlify. Navigation is defined in docs.json at the repository root. A hosted docs site is not live yet — until it is, read the Markdown in the repo. If your change alters behaviour, update the page that describes it — a feature with stale docs is a feature people cannot use.

.docs-meta/STYLE.md is the style contract: front matter, callout and tab usage, mermaid conventions, naming, and the rule that every value must come from the source rather than from memory.

New page? Add it to the matching tab and group in docs.json, or Mintlify will not show it. Preview with npx mint dev from the repository root.

Reporting security issues

Do not open a public issue for a vulnerability. Follow the Security policy.

Code of conduct

Participation is governed by the Code of conduct. Be respectful, assume good faith, and keep criticism on the work.

Licence

Contributions are accepted under the Apache License 2.0. By opening a pull request you agree your contribution may be distributed under it. See License.

Related

• Local setup
• Testing
• Repository layout