Contributing to VoiceGateway

Thank you for your interest in contributing to VoiceGateway. This guide covers everything you need to get started, whether you are reporting a bug, suggesting a feature, or submitting code.

Code of Conduct

We follow the Contributor Covenant Code of Conduct. Please read it before participating. In short: be respectful, be constructive, and assume good intent.

Ways to contribute

Report a bug

1. Search existing issues to check if it has already been reported
2. Open a new issue using the Bug Report template
3. Include: VoiceGateway version (voicegw --version), Python version, OS, and a minimal reproducible example
4. Attach relevant logs (redact API keys)

Suggest a feature

1. Open an issue using the Feature Request template
2. Describe the use case, not just the solution
3. If proposing a new provider, include links to the provider's API docs and pricing

Submit a pull request

We welcome PRs for bug fixes, new providers, documentation improvements, and new features. Follow this process:

1. Fork the repository on GitHub
2. Create a branch from main using the naming convention:
   • feat/<description> for features
   • fix/<description> for bug fixes
   • docs/<description> for documentation
   • test/<description> for test-only changes
3. Set up your development environment
4. Make your changes following the code style guide
5. Write tests for any new or changed behavior (see testing guide)
6. Run the full test suite -- pytest must pass
7. Run linters -- ruff check and mypy must pass
8. Commit with Conventional Commits format
9. Open a PR against main with a clear description of what and why
10. Respond to review feedback -- maintainers aim to review within 48 hours

Improve documentation

Documentation source lives in docs/ and is rendered by mahimailabs/voicegateway-web at https://voicegateway.mahimai.ca/docs. See development setup for the current preview and rebuild flow. Even small fixes (typos, broken links, clearer examples) are valuable.

PR checklist

Before opening your PR, verify:

• Tests pass: pytest
• Linting passes: ruff check .
• Type checking passes: mypy
• New public APIs have Google-style docstrings
• Commit messages use Conventional Commits format
• Documentation is updated if behavior changed
• No secrets or API keys in the diff

First-time contributors

Look for issues labeled good first issue. These are scoped, well-documented tasks suitable for newcomers. Common first contributions:

• Adding a new provider (follow the provider guide)
• Improving test coverage for an existing module
• Fixing a documentation gap
• Adding a pricing entry to the catalog

Getting help

• Open a GitHub Discussion for questions
• Tag @mahimai on issues if you are blocked

Related pages

• Development Setup
• Adding a Provider
• Refreshing the Pricing Catalogs
• Code Style
• Testing
• Troubleshooting