Contributing

Contributing

Prerequisites

• Go 1.24+
• Docker (for integration tests only)
• golangci-lint (for linting)
• gofmt (included with Go)

---

Setup

git clone https://github.com/iamvirul/deepdiff-db.git
cd deepdiff-db

# Install dependencies
go mod download

# Build
go build ./cmd/deepdiffdb/...

# Run unit tests
go test ./tests/config ./tests/content ./tests/checkpoint \
        ./tests/drivers ./tests/schema ./internal/schema ./internal/content

# Run integration tests (requires Docker)
go test -tags integration ./tests/schema/...

---

Project Layout

cmd/deepdiffdb/   CLI entry point
internal/         Private packages (schema, content, checkpoint, drivers, cli, report)
pkg/              Shared packages (config, logger, progress, errors)
tests/            Test files (mirrors package structure)
website/docs/     Documentation site source
scripts/          Local build scripts
samples/          Example configs and output

See Architecture Overview for the full module map.

---

Running Tests

Unit Tests

go test -race -coverprofile=coverage.txt \
  -coverpkg=./internal/...,./pkg/... \
  ./tests/config ./tests/content ./tests/checkpoint \
  ./tests/drivers ./tests/schema \
  ./internal/schema ./internal/content

Integration Tests

Integration tests use testcontainers-go to spin up real databases. Docker must be running.

go test -tags integration ./tests/schema/...

Integration test files are identified by the build tag //go:build integration at the top of the file.

Coverage

go tool cover -func=coverage.txt | tail -1
# target: 80%+ overall

---

Code Standards

Formatting

All code must be gofmt-clean:

gofmt -w ./...

Linting

golangci-lint run ./...

Key rules enforced:

• gosimple — no redundant nil checks, prefer idiomatic Go
• golint — exported types and functions must have doc comments
• No blank imports without justification comments
• No stutter in package-qualified names (e.g. resolve.ResolveConflicts → resolve.Conflicts)

Error Handling

Always use the typed error system in pkg/errors/:

// Good
return errors.Wrap(err, errors.ErrHashingFailed, "failed to hash table").
    With("table", tableName)

// Bad — never swallow or return plain errors from internal code
return fmt.Errorf("hash failed: %w", err)

Logging

Use structured logging with context fields, never bare strings:

log := logger.FromContext(ctx)
log.Info("hashing table", "table", tableName, "batch_size", batchSize)

Never log passwords, tokens, or PII.

Tests

• One test file per source file, in tests/<package>/
• Test behavior, not implementation
• No mocking your own code — only mock at system boundaries (DB, HTTP, filesystem)
• Error path coverage is required for all public functions
• Use platform-independent file tricks to trigger OS errors (see existing tests for patterns)

---

Branching Strategy

Branch	Purpose
main	Stable, releasable code
development	Integration branch for in-progress features
feature/<name>	Individual feature or fix branches
hotfix/<name>	Critical production fixes

PRs target development for features, main for hotfixes.

---

Commit Message Format

Follow Conventional Commits:

<type>(<scope>): <short description>

Types: feat, fix, docs, refactor, test, chore, perf
Scope: schema, content, drivers, config, cli, checkpoint, errors, ci

Examples:
  feat(content): add keyset pagination for large tables
  fix(schema): handle nullable columns with empty default in PostgreSQL
  test(checkpoint): add error path tests for atomic write
  docs(wiki): add contributing guide

---

Pull Request Checklist

• gofmt -w ./... — no formatting violations
• golangci-lint run ./... — no lint issues
• All unit tests pass
• New code has tests (error paths included)
• No secrets or credentials in code or tests
• PR title follows Conventional Commits format
• Description explains why, not just what

---

Adding a New Database Driver

1. Add the Go driver import to internal/drivers/imports.go with a comment
2. Add DSN construction to drivers.BuildDSN() in internal/drivers/drivers.go
3. Add schema introspection queries to internal/schema/introspect.go
4. Add cursor (pagination) SQL to internal/content/cursor.go
5. Add migration SQL generation to internal/schema/migrate.go
6. Add FK disable/enable SQL to internal/content/pack.go
7. Add a test container definition and integration tests in tests/schema/
8. Update Driver Support wiki page

---

Filing Issues

Use GitHub Issues. Include:

• DeepDiff DB version (deepdiff-db --version)
• Database driver and version
• Config file (with credentials redacted)
• Full error output with --log-level debug
• Steps to reproduce