# Contributing To QuickVoice

Thanks for helping improve QuickVoice. This repo is open source so teams can inspect, self-host, and extend AI phone-agent infrastructure.

## Positioning Guardrails

QuickVoice is the open-source, self-hostable Retell alternative for teams that want more control over AI phone-agent infrastructure. When you touch public copy, docs, examples, or launch material:

- Emphasize control, self-hosting, privacy review, cost visibility, and extensibility.
- Compare against closed hosted APIs by explaining tradeoffs, not by attacking competitors.
- Do not invent customer metrics, benchmarks, screenshots, compliance status, or provider partnerships.
- Be explicit when real calls, billing, OAuth, email, storage, or production deployment require external credentials and operational decisions.

## Good First Contributions

A good first contribution should be scoped enough that a new contributor can finish it without production credentials, product decisions, or deep architecture context.

Good candidates:

- Bug fixes with a clear reproduction and a small expected behavior.
- Documentation improvements for local setup, telephony providers, deployment, or env boundaries.
- Tests for existing behavior.
- Broken links, confusing copy, or missing setup notes in docs and launch material.
- Small product improvements that follow existing UI patterns and do not introduce a new dependency or migration.
- Integration notes for LiveKit, Twilio, Telnyx, Stripe, Postgres, or S3-compatible storage when they document current behavior.

Poor first issues:

- Changes that require live customer data, paid services, provider dashboards, or production secrets.
- New auth, billing, telephony, database, worker-runtime, or deployment architecture.
- Broad redesigns, new provider integrations, or compliance claims.
- Performance, cost, customer, or reliability claims without public evidence.

For larger changes, open an issue first so we can agree on the approach before you spend time on implementation.

During launch windows, maintainers should keep first-time contributors unblocked with a short first response even when a full answer needs more investigation. See [Launch Day Triage](./docs/launch/launch-day-triage.md) for response expectations and good-first-issue criteria.

## Non-Code Support

If QuickVoice is useful but you are not ready to open an issue or PR, starring the GitHub repo helps surface interest in open voice-agent infrastructure. Setup reports and docs feedback are still more actionable than stars when something is unclear or broken.

## Local Setup

QuickVoice uses `pnpm@9.0.0`, Turborepo, Docker, Postgres, Node.js `>=18`, and Python for the AI worker.

```sh
task up:dev
```

Useful checks:

```sh
pnpm lint
pnpm check-types
pnpm test
pnpm build
pnpm ci:local
pnpm audit:deps -- --audit-level high
```

Run the narrowest check that proves your change, then run broader checks when touching shared code, API contracts, auth, billing, database models, or runtime agent behavior.

## Pull Request Guidelines

- Keep PRs focused on one change.
- Describe the user-facing impact.
- Include screenshots or recordings for UI changes.
- Include test evidence in the PR body.
- Avoid unrelated formatting or dependency churn.
- Do not commit local env files, credentials, generated secrets, or private customer data.

## Development Notes

- `apps/web` contains the public website.
- `apps/console` contains the product console.
- `apps/server` contains the API and Prisma schema.
- `apps/ai` contains the Python AI service and LiveKit worker handlers.
- Shared TypeScript and lint configuration live under `packages/`.

## License

By contributing, you agree that your contributions are licensed under the GNU Affero General Public License v3.0, as described in [LICENSE](./LICENSE).
