開發工作流程

從 main 建立 branch，並依 github_username/short-description 格式命名，例如 caidanw/fix-database-timeout。

每次 commit 時執行的項目

Commit 時會自動執行 pre-commit hooks，設定檔是 repository root 的 .pre-commit-config.yaml。Hooks 會檢查檔名大小寫衝突、遺留的 merge conflict markers 與未移除的 Python debugger calls；驗證 JSON 與 TOML；將 line endings 統一為 LF；使用 Ruff lint 及 format Python；並以 mypy 進行 type checking。osprey_ui/ 內的變更也會通過 Prettier 與 ESLint。

Hooks 會在第一個 failure 停止，其中一些 hooks 會直接修改檔案。若 hook 修改檔案，請重新 stage 後再 commit。

Push 前檢查變更

CI 會針對整個 repository 執行相同 hooks，可以先使用下列 command 找出問題。

uv run pre-commit run --all-files

也可以直接執行個別工具。

# 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

使用 Conventional Commits 格式。以下是 repository history 中的實際範例。

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