Contributing

Thank you for your interest in contributing to Voicebox! This guide will help you get started.

Code of Conduct

  • Be respectful and inclusive
  • Welcome newcomers and help them learn
  • Focus on constructive feedback
  • Respect different viewpoints and experiences

Getting Started

Before you start contributing, make sure you have:

  1. Read the documentation to understand how Voicebox works
  2. Set up your development environment — see Development Setup
  3. Explored the codebase to understand the project structure
  4. Checked docs/PROJECT_STATUS.md — the living engineering roadmap that tracks prioritized tasks (Tier 1 → 3), architectural bottlenecks, and candidate TTS engines under evaluation (including why some are backlogged)
  5. Checked existing issues to see if someone else is working on something similar

Ways to Contribute

Report Bugs

Found a bug? Open an issue with reproduction steps

Request Features

Have an idea? Start a discussion or open an issue

Improve Docs

Fix typos, add examples, or clarify instructions

Write Code

Fix bugs, add features, or optimize performance

Development Workflow

1. Fork & Clone

# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/YOUR_USERNAME/voicebox.git
cd voicebox

2. Create a Branch

Use descriptive branch names:

# For features
git checkout -b feature/voice-effects

# For bug fixes
git checkout -b fix/audio-playback-issue

# For documentation
git checkout -b docs/api-examples

3. Make Your Changes

Follow these guidelines:

Code Style

TypeScript/React:

  • Use TypeScript strict mode
  • Prefer functional components with hooks
  • Use named exports
  • Format with Biome (runs automatically)

Python:

  • Follow PEP 8
  • Use type hints
  • Use async/await for I/O
  • Document functions with docstrings

Rust:

  • Follow Rust conventions
  • Use meaningful names
  • Handle errors explicitly
  • Run rustfmt
Commit Messages

Write clear, descriptive commit messages:

# Good
git commit -m "Add voice profile export feature"
git commit -m "Fix audio playback stopping after 30 seconds"


Avoid


git commit -m "Update code"
git commit -m "Fix bug"

Format:

  • Use imperative mood ("Add feature" not "Added feature")
  • Keep first line under 50 characters
  • Add detailed description if needed
Testing
  • Test your changes manually in the app
  • Ensure backend API endpoints work
  • Check for TypeScript/Python errors
  • Verify UI components render correctly
  • Add automated tests when possible

4. Push & Create PR

# Push your branch
git push origin feature/your-feature-name

# Then create a pull request on GitHub

Pull Request Guidelines

When creating a pull request:

Use a Clear Title

Examples:

  • "Add voice profile export functionality"
  • "Fix audio playback stopping after 30 seconds"
  • "Improve generation speed with caching"

Provide Description

Include:

  • What changes you made
  • Why you made them
  • How to test them
  • Screenshots (for UI changes)
  • Reference related issues

Update Documentation

  • Update relevant docs if behavior changes
  • Add API documentation for new endpoints
  • Update README if needed

Check the Checklist

  • Code follows style guidelines
  • Documentation updated
  • Changes tested
  • No breaking changes (or documented)
  • CHANGELOG.md updated

Project Structure

Areas for Contribution

Bug Fixes

  • Check existing issues for bugs
  • Test your fix thoroughly
  • Add regression tests if possible

New Features

  • Check docs/PROJECT_STATUS.md and the roadmap before proposing work — the status doc lists prioritized tasks (Tier 1 → 3), known architectural bottlenecks, and candidate TTS engines already under evaluation (including why some have been backlogged)
  • Discuss major features in an issue first
  • Keep features focused and well-scoped
  • Adding a new TTS engine? See TTS Engines for the phased workflow

Documentation

  • Improve clarity and fix typos
  • Add code examples
  • Create tutorials or guides
  • Document API endpoints

UI/UX Improvements

  • Improve accessibility
  • Enhance visual design
  • Optimize performance
  • Add animations/transitions

Infrastructure

  • Improve build process
  • Add CI/CD improvements
  • Optimize bundle size
  • Add testing infrastructure

API Development

When adding new API endpoints:

Add Route

In backend/main.py:

@app.post("/api/new-endpoint")
async def new_endpoint(data: RequestModel) -> ResponseModel:
"""Endpoint description."""
# Implementation
return response

Create Models

In backend/models.py:

class RequestModel(BaseModel):
field: str


class ResponseModel(BaseModel):
result: str

Regenerate Client

just generate-api

This updates the TypeScript client with type-safe bindings.

Update Docs

The API documentation is automatically generated from the OpenAPI schema. Ensure your endpoint has proper docstrings and type hints, then regenerate the docs:

just generate-api

Testing

Currently testing is primarily manual. When adding tests:

Backend:

cd backend
pytest

Frontend:

bun run test

E2E (future):

bun run test:e2e

Release Process

Releases are managed by maintainers using bumpversion:

# Bump version (patch, minor, or major)
bumpversion patch

# Push with tags
git push && git push --tags

GitHub Actions automatically builds and publishes releases when tags are pushed.

Community

  • GitHub Issues: Bug reports and feature requests
  • GitHub Discussions: General questions and ideas
  • Discord: Real-time chat (coming soon)

Recognition

Contributors are recognized in:

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Questions?

If you have questions:

  1. Check the documentation
  2. Read docs/PROJECT_STATUS.md for current engineering priorities
  3. Search existing issues
  4. Open a new issue or discussion
  5. See CONTRIBUTING.md in the repo

Thank you for contributing to Voicebox! 🎉