93 lines (67 loc) · 2.03 KB

Contributing to TOONDB

Thanks for contributing to TOONDB.

Prerequisites

Go 1.22+
Docker (recommended for runtime verification)

Local Setup

go test ./...

Run service locally:

go run ./cmd/toondb-service -host 127.0.0.1 -port 6767 -tenant dev -data-dir ./data-go

Project Areas

engine/ core database operations
storage/ append store + WAL
index/ hash index persistence
parser/ TOON/JSON parsing and serialization
query/ filter matching and planning
service/ HTTP service layer
cmd/toondb-service/ service entrypoint
cmd/toondb-bridge/ stdin/stdout bridge entrypoint

Development Guidelines

Keep changes focused and minimal.
Maintain backward compatibility for service API unless explicitly breaking.
Add tests for behavioral changes.
Preserve deterministic and clear error messages.
Avoid introducing unnecessary dependencies.

Testing Expectations

Before opening a PR:

go test ./...

If service-layer behavior changed, also validate:

Local service health/auth works.
CRUD endpoints still behave correctly.
Bridge endpoint (/v1/bridge) behavior is correct.

Detailed commands:

TESTING.md

Docker Validation (Recommended)

docker compose up -d --build
docker compose logs --tail 100

Confirm:

service starts cleanly
health endpoint responds
data volume permissions are correct

Pull Request Checklist

Code compiles and tests pass
New/changed behavior covered by tests
README/docs updated where needed
No unrelated refactors mixed in
Breaking changes are clearly called out

Commit Message Guidance

Suggested prefixes:

feat: new functionality
fix: bug fix
docs: documentation updates
test: test changes
refactor: internal cleanup without behavior change

Reporting Issues

Please include:

environment details (OS, Go version, Docker version if relevant)
minimal reproduction steps
expected vs actual behavior
logs/error output