Contributing

Contributions are welcome. Bug reports, feature ideas, and pull requests all help.

Development Setup

git clone https://github.com/gopackx/go-audit
cd go-audit
go mod download

Go 1.22 or later is required (matches the go.mod directive).

Running Tests

The core tests run against SQLite in-memory (no setup required). Integration tests against PostgreSQL and MySQL use Docker:

docker compose up -d          # starts pg + mysql
go test ./...

Run only the core (SQLite-backed) tests:

go test ./...                 # uses in-memory store by default
go test ./integration/...     # requires Docker

Project Layout

.
├── audit.go, auditor.go, api_auditor.go   core types and implementations
├── config.go, types.go                    Config, structs, validation
├── diff.go, redact.go                     diff engine, redaction helpers
├── transaction.go, aliases.go             context helpers, re-exports
├── dialect/                               PG / MySQL / SQLite dialects
├── store/                                 Store interface, SQL + in-memory
├── migrate/                               schema creation
├── entry/                                 persistent types (AuditLog, …)
├── adapters/
│   ├── gorm/                              GORM plugin
│   ├── bun/                               Bun QueryHook
│   └── ent/                               Ent mutation hook
└── _examples/                             runnable end-to-end samples

Adding a New Adapter

1. Create a new package under adapters/<orm>.
2. Expose a registration entry point. Existing patterns:
   • GORM — Plugin(auditor) gorm.Plugin
   • Bun — Register(db, auditor)
   • Ent — Hook(auditor) ent.Hook
3. Hook into the ORM's lifecycle to capture create, update, and delete events.
4. Reuse the core Auditor via RecordDataChange — don't duplicate diff or exclusion logic.
5. Add a full test suite that mirrors adapters/gorm's layout.

See adapters/gorm for the reference implementation.

Adding a New Dialect

1. Implement dialect.Dialect for your target database.
2. Register via audit.RegisterDialect(DialectType("name"), impl).
3. Add dialect tests parallel to the built-ins under dialect/.

Code Style

• gofmt + goimports.
• golangci-lint run passes with the repo's config.
• Conventional commits: feat: ..., fix: ..., docs: ..., chore: ....

Pull Request Process

1. Fork, branch from main.
2. Commit with conventional messages.
3. Push and open a PR. CI must be green.
4. A maintainer will review — please address comments and squash as requested.

Reporting Issues

Use the GitHub issue tracker. Include:

• Go version and OS
• ORM + database + dialect
• A minimal reproduction if possible
• What you expected vs what happened