From 827ce2bf0a4cec11b8323f5046a1820dbb95a01b Mon Sep 17 00:00:00 2001 From: Jamie Pine Date: Sun, 26 Jul 2026 23:17:34 -0700 Subject: [PATCH] docs: refresh contributor docs and drop root requirements.txt MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CONTRIBUTING.md caught up with reality: ruff not Black, Python 3.12, sh.voicebox.app, the routes/services/backends layout, the actual pytest + CI story, and a working autoupdater link. SECURITY.md now says 0.5.x and describes what CI actually enforces. The root requirements.txt was vestigial (unpinned, included torchvision, referenced by nothing) — deleted, with two stale doc references repointed at backend/requirements.txt. backend/pyproject.toml is now covered by bumpversion; its version was stuck at 0.2.3 and is synced to 0.5.0. --- .bumpversion.cfg | 4 ++ CONTRIBUTING.md | 50 +++++++++---------- SECURITY.md | 8 +-- docs/content/docs/developer/contributing.mdx | 16 +----- docs/content/docs/developer/setup.mdx | 17 ++----- .../content/docs/overview/troubleshooting.mdx | 33 ------------ docs/plans/DOCKER_DEPLOYMENT.md | 2 +- requirements.txt | 9 ---- 8 files changed, 40 insertions(+), 99 deletions(-) delete mode 100644 requirements.txt diff --git a/.bumpversion.cfg b/.bumpversion.cfg index 6d70587e..f03d389b 100644 --- a/.bumpversion.cfg +++ b/.bumpversion.cfg @@ -37,3 +37,7 @@ replace = "version": "{new_version}" [bumpversion:file:backend/__init__.py] search = __version__ = "{current_version}" replace = __version__ = "{new_version}" + +[bumpversion:file:backend/pyproject.toml] +search = version = "{current_version}" +replace = version = "{new_version}" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b4a3b0ea..7a42b26c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,9 +18,9 @@ Thank you for your interest in contributing to Voicebox! This document provides curl -fsSL https://bun.sh/install | bash ``` -- **[Python 3.11+](https://python.org)** - For backend development +- **[Python 3.12+](https://python.org)** - For backend development ```bash - python --version # Should be 3.11 or higher + python --version # Should be 3.12 or higher ``` - **[Rust](https://rustup.rs)** - For Tauri desktop app (installed automatically by Tauri CLI) @@ -91,7 +91,7 @@ On Windows, to build with CUDA support for local testing: just build-local # Build CPU + CUDA server binaries + Tauri installer ``` -This builds the CPU sidecar (bundled with the app), the CUDA binary (placed in `%APPDATA%/com.voicebox.app/backends/` for runtime GPU switching), and the installable Tauri app. +This builds the CPU sidecar (bundled with the app), the CUDA binary (placed in `%APPDATA%/sh.voicebox.app/backends/` for runtime GPU switching), and the installable Tauri app. Creates platform-specific installers (`.dmg`, `.msi`, `.AppImage`) in `tauri/src-tauri/target/release/bundle/`. @@ -115,14 +115,6 @@ just build-server This makes PyInstaller use your local qwen-tts version instead of the pip-installed package. -### Generate OpenAPI Client - -After starting the backend server: -```bash -./scripts/generate-api.sh -``` -This downloads the OpenAPI schema and generates the TypeScript client in `app/src/lib/api/` - ### Convert Assets to Web Formats To optimize images and videos for the web, run: @@ -212,7 +204,7 @@ export const ProfileCard = (props) => { ... } - Follow PEP 8 style guide - Use type hints - Use async/await for I/O operations -- Format with Black (if configured) +- Format and lint with ruff (configured in `backend/pyproject.toml`) ```python # Good @@ -242,9 +234,12 @@ voicebox/ │ ├── lib/ # Utilities and API client │ └── hooks/ # React hooks ├── backend/ # Python FastAPI server -│ ├── main.py # API routes -│ ├── tts.py # Voice synthesis -│ └── ... +│ ├── main.py # Entry point (FastAPI app assembled in app.py) +│ ├── routes/ # API routers, one per domain +│ ├── services/ # Business logic (generation, transcription, profiles, ...) +│ ├── backends/ # TTS engine implementations +│ ├── database/ # SQLAlchemy models, sessions, migrations +│ └── tests/ # pytest suite ├── tauri/ # Desktop app wrapper │ └── src-tauri/ # Rust backend └── scripts/ # Build scripts @@ -289,23 +284,26 @@ voicebox/ When adding new API endpoints: -1. **Add route in `backend/main.py`** +1. **Add the route to the relevant router in `backend/routes/`** (new routers get registered in `backend/routes/__init__.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 - ``` +5. **Update the TypeScript client** — add matching types to `app/src/lib/api/types.ts` and a method to `app/src/lib/api/client.ts` 6. **Update `backend/README.md`** with endpoint documentation ## Testing -Currently, testing is primarily manual. When adding tests: +Backend tests live in `backend/tests/` and run with pytest: -- **Backend**: Use pytest for Python tests -- **Frontend**: Use Vitest for React component tests -- **E2E**: Use Playwright for end-to-end tests (future) +```bash +cd backend +venv/bin/python -m pytest tests +``` + +CI runs the backend test suite on every PR, along with frontend lint and typecheck (`bun run lint`, `bun run typecheck`) and a `cargo check` of the Tauri app (see `.github/workflows/ci.yml`). Add backend tests alongside your changes where it makes sense. + +- **Frontend**: Vitest for React component tests (coverage is still sparse — contributions welcome) +- **E2E**: Playwright for end-to-end tests (future) ## Pull Request Process @@ -363,7 +361,7 @@ See [docs/content/docs/overview/troubleshooting.mdx](docs/content/docs/overview/ **Quick fixes:** -- **Backend won't start:** Check Python version (3.11+), ensure venv is activated, install dependencies +- **Backend won't start:** Check Python version (3.12+), ensure venv is activated, install dependencies - **Tauri build fails:** Ensure Rust is installed, clean build with `cd tauri/src-tauri && cargo clean` - **OpenAPI client generation fails:** Ensure backend is running, check `curl http://localhost:17493/openapi.json` @@ -379,7 +377,7 @@ See [docs/content/docs/overview/troubleshooting.mdx](docs/content/docs/overview/ - [README.md](README.md) - Project overview - [backend/README.md](backend/README.md) - API documentation - [docs/PROJECT_STATUS.md](docs/PROJECT_STATUS.md) - Living engineering roadmap: architecture, shipped vs in-flight work, prioritized open issues, candidate TTS engines under evaluation, architectural bottlenecks. Keep this updated when you ship significant features, close or backlog a model integration, or identify new bottlenecks. -- [docs/AUTOUPDATER_QUICKSTART.md](docs/AUTOUPDATER_QUICKSTART.md) - Auto-updater setup +- [docs/content/docs/developer/autoupdater.mdx](docs/content/docs/developer/autoupdater.mdx) - Auto-updater setup (published at [voicebox.sh docs](https://voicebox.sh/docs/developer/autoupdater)) - [SECURITY.md](SECURITY.md) - Security policy - [CHANGELOG.md](CHANGELOG.md) - Version history diff --git a/SECURITY.md b/SECURITY.md index 049dd778..fa837b21 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -6,8 +6,8 @@ We release patches for security vulnerabilities. Which versions are eligible for | Version | Supported | | ------- | ------------------ | -| 0.3.x | :white_check_mark: | -| < 0.3 | :x: | +| 0.5.x | :white_check_mark: | +| < 0.5 | :x: | ## Reporting a Vulnerability @@ -39,7 +39,7 @@ We will: ### For Developers - **Dependencies** - Keep all dependencies up to date -- **Code review** - All PRs require review before merging +- **CI checks** - Every PR must pass typecheck, lint, backend tests, and `cargo check` before merging - **Secrets** - Never commit API keys or signing keys - **Signing** - All releases are cryptographically signed @@ -82,7 +82,7 @@ Timeline may vary based on severity and complexity. ## Security Updates Security updates will be: -- Released as patch versions (e.g., 0.3.2) +- Released as patch versions (e.g., 0.5.1) - Documented in CHANGELOG.md - Announced via GitHub releases - Automatically delivered via auto-updater diff --git a/docs/content/docs/developer/contributing.mdx b/docs/content/docs/developer/contributing.mdx index 4b7785a1..0ae17ecd 100644 --- a/docs/content/docs/developer/contributing.mdx +++ b/docs/content/docs/developer/contributing.mdx @@ -258,20 +258,8 @@ When adding new API endpoints: ``` - - ```bash - just generate-api - ``` - - This updates the TypeScript client with type-safe bindings. - - - - The API documentation is automatically generated from the OpenAPI schema. Ensure your endpoint has proper docstrings and type hints, then regenerate the docs: - - ```bash - just generate-api - ``` + + The TypeScript client is hand-written. Add matching types to `app/src/lib/api/types.ts` and a method to `app/src/lib/api/client.ts`. The backend's live schema at `http://localhost:17493/docs` is the reference. diff --git a/docs/content/docs/developer/setup.mdx b/docs/content/docs/developer/setup.mdx index 975eb6f1..ef185216 100644 --- a/docs/content/docs/developer/setup.mdx +++ b/docs/content/docs/developer/setup.mdx @@ -32,7 +32,7 @@ Ensure you have these installed: curl -fsSL https://bun.sh/install | bash ``` - }> + }> [Download Python](https://python.org) ```bash python --version @@ -111,7 +111,6 @@ Run `just --list` to see all available commands. Highlights: | Command | Description | |---------|-------------| -| `just generate-api` | Generate TypeScript API client from the backend's OpenAPI schema | | `just docs` | Open `http://localhost:17493/docs` in your browser | | `just logs` | Tail backend logs | | `just clean` | Remove build artifacts | @@ -184,15 +183,9 @@ See [Model Management](/developer/model-management) for the full list. First-time usage will be slower due to model downloads, but subsequent runs will use cached models. -## Generate OpenAPI Client +## Frontend API Client -After starting the backend server, generate the TypeScript API client: - -```bash -just generate-api -``` - -This downloads the OpenAPI schema and generates the TypeScript client in `app/src/lib/api/`. +The TypeScript API client is hand-written: request/response types live in `app/src/lib/api/types.ts` and the fetch wrapper in `app/src/lib/api/client.ts`. When you add or change a backend endpoint, update both to match. The backend's live schema at `http://localhost:17493/docs` is the reference. ## Manual Setup (Advanced) @@ -277,9 +270,9 @@ bun run tauri dev - - Check Python version (must be 3.11+) + - Check Python version (must be 3.12+) - Ensure virtual environment is activated: `source backend/venv/bin/activate` - - Verify all dependencies are installed: `pip install -r requirements.txt` + - Verify all dependencies are installed: `pip install -r backend/requirements.txt` - Check if port 17493 is available diff --git a/docs/content/docs/overview/troubleshooting.mdx b/docs/content/docs/overview/troubleshooting.mdx index f615b3c6..c97176a9 100644 --- a/docs/content/docs/overview/troubleshooting.mdx +++ b/docs/content/docs/overview/troubleshooting.mdx @@ -355,39 +355,6 @@ cd ../.. bun run tauri build ``` -### OpenAPI Client Generation Fails - -**Symptoms:** -- `./scripts/generate-api.sh` fails -- "Failed to fetch schema" error - -**Solutions:** - - - - ```bash - curl http://localhost:17493/openapi.json - ``` - - Should return JSON. If not, start the backend. - - - - Ensure nothing else is using port 17493 - - - - ```bash - cd backend - source venv/bin/activate - uvicorn main:app --reload --port 17493 - - # In another terminal - ./scripts/generate-api.sh - ``` - - - ## Database Issues ### "Database is locked" Error diff --git a/docs/plans/DOCKER_DEPLOYMENT.md b/docs/plans/DOCKER_DEPLOYMENT.md index 6af65ed7..b95bd28b 100644 --- a/docs/plans/DOCKER_DEPLOYMENT.md +++ b/docs/plans/DOCKER_DEPLOYMENT.md @@ -90,7 +90,7 @@ RUN apt-get update && apt-get install -y \ # Copy application COPY backend/ /app/backend/ -COPY requirements.txt /app/ +COPY backend/requirements.txt /app/ # Install Python dependencies RUN pip install --no-cache-dir -r requirements.txt diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index ea444b9c..00000000 --- a/requirements.txt +++ /dev/null @@ -1,9 +0,0 @@ -uvicorn -fastapi -sqlalchemy -torch -torchvision -soundfile -librosa -python-multipart -huggingface_hub