mirror of
https://github.com/jamiepine/voicebox.git
synced 2026-09-15 04:40:40 -07:00
better docs
This commit is contained in:
Jamie Pine
+252
@@ -0,0 +1,252 @@
|
||||
# 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](https://bun.sh) - Package manager
|
||||
- [Rust](https://rustup.rs) - For Tauri desktop app
|
||||
- [Python 3.11+](https://python.org) - For backend
|
||||
- Git
|
||||
|
||||
### Development Setup
|
||||
|
||||
1. **Fork and clone the repository**
|
||||
```bash
|
||||
git clone https://github.com/YOUR_USERNAME/voicebox.git
|
||||
cd voicebox
|
||||
```
|
||||
|
||||
2. **Install dependencies**
|
||||
```bash
|
||||
bun install
|
||||
cd backend && pip install -r requirements.txt && cd ..
|
||||
```
|
||||
|
||||
3. **Set up the database**
|
||||
```bash
|
||||
cd backend
|
||||
python -c "from database import init_db; init_db()"
|
||||
```
|
||||
|
||||
4. **Start development**
|
||||
```bash
|
||||
# Terminal 1: Backend server
|
||||
bun run dev:server
|
||||
|
||||
# Terminal 2: Desktop app
|
||||
bun run dev
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### 1. Create a Branch
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
git commit -m "Add feature: voice profile export"
|
||||
git commit -m "Fix: audio playback stops after 30 seconds"
|
||||
```
|
||||
|
||||
### 5. Push and Create Pull Request
|
||||
|
||||
```bash
|
||||
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)
|
||||
|
||||
```typescript
|
||||
// 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)
|
||||
|
||||
```python
|
||||
# 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:**
|
||||
```bash
|
||||
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! 🎉
|
||||
Reference in New Issue
Block a user