voicebox/CONTRIBUTING.md

Contributing to Voicebox

Thank you for your interest in contributing to Voicebox! This document provides guidelines and instructions for contributing.

Code of Conduct

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

Getting Started

Prerequisites

• Bun - Package manager
• Rust - For Tauri desktop app
• Python 3.11+ - For backend
• Git

Development Setup

1. Fork and clone the repository

   git clone https://github.com/YOUR_USERNAME/voicebox.git
   cd voicebox
   

2. Install dependencies

   bun install
   cd backend && pip install -r requirements.txt && cd ..
   

3. Set up the database

   cd backend
   python -c "from database import init_db; init_db()"
   

4. Start development

   # Terminal 1: Backend server
   bun run dev:server
   
   # Terminal 2: Desktop app
   bun run dev
   

Development Workflow

1. Create a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

2. Make Your Changes

• Write clean, readable code
• Follow existing code style
• Add comments for complex logic
• Update documentation as needed

3. Test Your Changes

• Test manually in the app
• Ensure backend API endpoints work
• Check for TypeScript/Python errors
• Verify UI components render correctly

4. Commit Your Changes

Write clear, descriptive commit messages:

git commit -m "Add feature: voice profile export"
git commit -m "Fix: audio playback stops after 30 seconds"

5. Push and Create Pull Request

git push origin feature/your-feature-name

Then create a pull request on GitHub with:

• Clear description of changes
• Screenshots (for UI changes)
• Reference to related issues

Code Style

TypeScript/React

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

// Good
export function ProfileCard({ profile }: { profile: Profile }) {
  return <div>{profile.name}</div>;
}

// Avoid
export const ProfileCard = (props) => { ... }

Python

• Follow PEP 8 style guide
• Use type hints
• Use async/await for I/O operations
• Format with Black (if configured)

# Good
async def create_profile(name: str, language: str) -> Profile:
    """Create a new voice profile."""
    ...

# Avoid
def create_profile(name, language):
    ...

Rust

• Follow Rust conventions
• Use meaningful variable names
• Handle errors explicitly
• Format with rustfmt

Project Structure

voicebox/
├── app/              # Shared React frontend
│   └── src/
│       ├── components/   # UI components
│       ├── lib/          # Utilities and API client
│       └── hooks/        # React hooks
├── backend/          # Python FastAPI server
│   ├── main.py       # API routes
│   ├── tts.py        # Voice synthesis
│   └── ...
├── tauri/            # Desktop app wrapper
│   └── src-tauri/    # Rust backend
└── scripts/          # Build scripts

Areas for Contribution

🐛 Bug Fixes

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

✨ New Features

• Check the roadmap in README.md
• Discuss major features in an issue first
• Keep features focused and well-scoped

📚 Documentation

• Improve README clarity
• Add code comments
• Write API documentation
• Create tutorials or guides

🎨 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:

1. Add route in backend/main.py
2. Create Pydantic models in backend/models.py
3. Implement business logic in appropriate module
4. Update OpenAPI schema (automatic with FastAPI)
5. Regenerate TypeScript client:

   bun run generate:api
   

6. Update backend/README.md with endpoint documentation

Testing

Currently, testing is primarily manual. When adding tests:

• Backend: Use pytest for Python tests
• Frontend: Use Vitest for React component tests
• E2E: Use Playwright for end-to-end tests (future)

Pull Request Process

1. Update documentation if needed
2. Ensure code follows style guidelines
3. Test your changes thoroughly
4. Update CHANGELOG.md with your changes
5. Request review from maintainers

PR Checklist

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

Release Process

Releases are managed by maintainers:

1. Version bump in tauri.conf.json and Cargo.toml
2. Update CHANGELOG.md
3. Create git tag: git tag v0.2.0
4. Push tag: git push --tags
5. GitHub Actions builds and releases

Questions?

• Open an issue for bugs or feature requests
• Check existing issues and discussions
• Review the codebase to understand patterns

License

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

---

Thank you for contributing to Voicebox! 🎉