diff --git a/docs/development/WORKFLOW.md b/docs/development/WORKFLOW.md index 38e8e05..819b2d1 100644 --- a/docs/development/WORKFLOW.md +++ b/docs/development/WORKFLOW.md @@ -205,6 +205,69 @@ test(frontend): add unit tests for ProjectDashboard --- +## Pre-Commit Hooks + +The repository includes pre-commit hooks that enforce validation before commits on protected branches. + +### Setup + +Enable the hooks by configuring git to use the `.githooks` directory: + +```bash +git config core.hooksPath .githooks +``` + +This only needs to be done once per clone. + +### What the Hooks Do + +When committing to **protected branches** (`main`, `dev`): + +| Condition | Action | +|-----------|--------| +| Backend files changed | Runs `make validate` in `/backend` | +| Frontend files changed | Runs `npm run validate` in `/frontend` | +| No relevant changes | Skips validation | + +If validation fails, the commit is blocked with an error message. + +When committing to **feature branches**: +- Validation is skipped (allows WIP commits) +- A message reminds you to run validation manually if needed + +### Why Protected Branches Only? + +The hooks only enforce validation on `main` and `dev` for good reasons: + +1. **Feature branches are for iteration** - WIP commits, experimentation, and rapid prototyping shouldn't be blocked +2. **Flexibility during development** - You can commit broken code to your feature branch while debugging +3. **PRs catch issues** - The merge process ensures validation passes before reaching protected branches +4. **Manual control** - You can always run `make validate` or `npm run validate` yourself + +### Manual Validation + +Even on feature branches, you should validate before creating a PR: + +```bash +# Backend +cd backend && make validate + +# Frontend +cd frontend && npm run validate +``` + +### Bypassing Hooks (Emergency Only) + +In rare cases where you need to bypass the hook: + +```bash +git commit --no-verify -m "message" +``` + +**Use sparingly** - this defeats the purpose of the hooks. + +--- + ## Documentation Updates - Keep `docs/architecture/IMPLEMENTATION_ROADMAP.md` updated @@ -314,8 +377,11 @@ Do NOT use parallel agents when: | Action | Command/Location | |--------|-----------------| | Create branch | `git checkout -b feature/-` | +| Enable pre-commit hooks | `git config core.hooksPath .githooks` | | Run backend tests | `IS_TEST=True uv run pytest` | | Run frontend tests | `npm test` | +| Backend validation | `cd backend && make validate` | +| Frontend validation | `cd frontend && npm run validate` | | Check types (backend) | `uv run mypy src/` | | Check types (frontend) | `npm run type-check` | | Lint (backend) | `uv run ruff check src/` |