mirror of
https://github.com/furyhawk/agent_delta.git
synced 2026-07-21 02:05:36 +00:00
65 lines
2.4 KiB
Markdown
65 lines
2.4 KiB
Markdown
# Contributing to agent_delta
|
|
|
|
## Development setup
|
|
|
|
```bash
|
|
# Backend (uv-based)
|
|
cd backend
|
|
uv sync # install all deps including dev extras
|
|
cp .env.example .env # then fill in required vars (see ENV_VARS.md)
|
|
uv run uvicorn app.main:app --reload --port 8000
|
|
uv run alembic upgrade head # apply migrations
|
|
|
|
# Frontend (bun-based)
|
|
cd ../frontend
|
|
bun install
|
|
bun dev # http://localhost:3000
|
|
|
|
# Or everything in Docker
|
|
docker compose up
|
|
```
|
|
|
|
## Code style
|
|
|
|
- **Python:** ruff (`uv run ruff check . --fix && uv run ruff format .`). Line length 120.
|
|
- **Type hints:** modern syntax (`str | None`, `list[X]`, `dict[str, Any]`). Use `Annotated[T, Depends(...)]` for DI in route signatures.
|
|
- **TypeScript:** strict mode, no `any` unless typed external API. ESLint + Prettier (run `bun run lint`).
|
|
- **Imports:** stdlib → third-party → local, separated by blank lines. Use `TYPE_CHECKING` block to break circular refs.
|
|
- **Datetime:** `datetime.now(UTC)` not `datetime.utcnow()`.
|
|
- **Comparisons:** `secrets.compare_digest()` for tokens/keys (constant-time).
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
cd backend
|
|
uv run pytest # all backend tests
|
|
uv run pytest tests/test_file.py::test -v # single test
|
|
uv run pytest -k "name_substring" -v # by name pattern
|
|
uv run pytest --cov=app # with coverage
|
|
```
|
|
|
|
```bash
|
|
cd frontend
|
|
bun test # vitest
|
|
bunx tsc --noEmit # type-check without emit
|
|
```
|
|
|
|
## Architecture rules
|
|
|
|
- **Routes** never import repositories directly. Always go through a service.
|
|
- **Services** raise domain exceptions (`NotFoundError`, `AlreadyExistsError`) — never return `None` for "not found".
|
|
- **Repositories** use `db.flush()` + `db.refresh()`, NEVER `db.commit()` (session auto-commits in `get_db_session`).
|
|
- **Pydantic schemas:** separate `*Create`, `*Update`, `*Read`, `*List` per operation.
|
|
- **Migrations:** one Alembic revision per logical change; never edit a merged migration.
|
|
|
|
See `docs/architecture.md` for the full layered architecture rules.
|
|
|
|
## Pull-request checklist
|
|
|
|
- [ ] `uv run ruff check . && uv run ruff format --check .` clean
|
|
- [ ] `cd frontend && bunx tsc --noEmit` clean
|
|
- [ ] Tests added for new code paths; `uv run pytest` green
|
|
- [ ] If schema changed: alembic migration committed (`uv run alembic revision --autogenerate -m "..."`)
|
|
- [ ] Updated `ENV_VARS.md` if new env vars added
|
|
- [ ] Updated `CHANGELOG.md` (if applicable)
|