Skip to content

Contributing

Dev Setup

git clone git@github.com:ConflictHQ/kohakku.git
cd kohakku
make setup    # creates .env files, installs deps
make up       # starts docker-compose stack
make migrate  # runs migrations
make seed     # seeds demo data

Prerequisites

  • Docker and Docker Compose v2+
  • Python 3.12+ with uv
  • Go 1.22+
  • Node.js (for pre-commit hooks)

Running Tests

make test             # both services
make controller-test  # Django pytest (in container)
make dispatcher-test  # Go test (local, needs Postgres)
make test-integration # full dispatch loop (needs running stack)

Controller Tests

Tests run inside the container against a real database. Never mock the database.

# Run a specific test file
docker compose exec -T controller pytest tasks/tests/test_dispatch.py -v

# Run with output
docker compose exec -T controller pytest -s --tb=short

Dispatcher Tests

Tests run locally against a Postgres instance:

cd dispatcher
DATABASE_URL=postgres://postgres:postgres@localhost:5432/kohakku-dispatcher?sslmode=disable \
  go test ./... -v -count=1

Code Style

Python (Controller)

  • Formatter: Ruff (ruff format)
  • Linter: Ruff (ruff check)
  • Max line length: 140
  • Import sorting: handled by Ruff
make controller-format  # format
make controller-lint    # lint

Go (Dispatcher)

  • Formatter: gofmt
  • Linter: golangci-lint
make dispatcher-format  # format
make dispatcher-lint    # lint

Both

make format  # format both
make lint    # lint both

Commit Style

Use conventional commits:

Prefix When
feat: New feature
fix: Bug fix
docs: Documentation only
test: Adding or updating tests
ci: CI/CD changes
chore: Maintenance, deps, tooling

Pre-commit hooks are configured in .pre-commit-config.yaml.

PR Process

  1. Create a branch from main (feature/42-description or fix/42-description)
  2. Make changes, add tests
  3. Run make lint && make test
  4. Open PR with description and test plan
  5. CI must pass (lint + test + build)

PR Description

Include:

  • What changed and why
  • Test plan (how to verify)
  • Link to the issue (fixes #42)

Architecture

Component Language Framework Tests
Controller Python 3.12 Django + DRF + HTMX pytest
Dispatcher Go 1.22 Chi + HTMX go test
Agent images Dockerfile Multi-stage builds agent-test image
Infrastructure HCL Terraform --

Key Principles

  • Auth check on every endpoint. First line.
  • Soft deletes only on business objects. Never hard delete.
  • No integer PKs in APIs -- UUID, slug, or content-addressed keys.
  • Validate at boundaries. All input validated at API entry points.
  • Errors should never pass silently.
  • Tests hit a real database. Never mock it.