Development Workflow

Branch from main and name your branch github_username/short-description (e.g. caidanw/fix-database-timeout).

What runs on every commit

Pre-commit hooks run automatically when you commit; the config is .pre-commit-config.yaml at the repo root. The hooks check for filename case conflicts, leftover merge-conflict markers, and forgotten Python debugger calls; validate JSON and TOML; normalize line endings to LF; lint and format Python with Ruff; and type-check with mypy. Changes under osprey_ui/ also go through Prettier and ESLint.

Hooks stop at the first failure, and several fix files in place—if a hook modifies a file, re-stage it and commit again.

Checking your work before you push

CI runs the same hooks against the whole repo, so you can catch failures ahead of time with:

uv run pre-commit run --all-files

Or run the individual tools directly:

# Lint and format
uv run ruff check
uv run ruff format

# Type check a specific module, or everything with `uv run mypy .`
uv run mypy osprey_worker/src/osprey/worker/lib

Commit messages

Follow the Conventional Commits format. Real examples from this repo’s history:

fix(ui): show the event-stream timezone once, not twice
build(deps): remove unused Discord-era Python dependencies