relspecgo/CONTRIBUTING.md

Contributing to RelSpec

Setup

• Go 1.25+ (see go.mod), Git
• Optional: golangci-lint, Docker/Podman (PostgreSQL integration tests)

git clone git@git.warky.dev:wdevs/relspecgo.git
cd relspecgo
make deps
make build        # outputs build/relspec

Make Targets

Target	Purpose
make test	Unit tests (race detection, coverage)
make test-integration	Integration tests (needs RELSPEC_TEST_PG_CONN)
make docker-test	PostgreSQL integration tests via Docker/Podman
make lint	golangci-lint
make fmt / fmt-check	gofumpt + goimports
make check	vet, fmt-check, staticcheck, govulncheck
make coverage	Coverage report

Single test: go test -run TestName ./pkg/readers/dbml

Layout

cmd/relspec/      CLI commands (convert, diff, merge, split, edit, inspect, job, ...)
pkg/models/       Core model: Database > Schema > Table > Column/Constraint/Index/Relationship
pkg/readers/<fmt> One reader per format
pkg/writers/<fmt> One writer per format
pkg/diff, merge, inspector, jobs, transform, ui, pgsql, sqltypes ...
examples/         Sample files
tests/            Integration tests and assets
docs/             Feature docs

Adding a Reader

1. Create pkg/readers/<format>/reader.go with NewReader(options *readers.ReaderOptions).
2. Implement readers.Reader: ReadDatabase, ReadSchema, ReadTable.
3. Add reader_test.go in the same package.
4. Register the format in the CLI switches (cmd/relspec/convert.go, diff.go, edit.go, ...).
5. Add a README.md in the reader directory.

Adding a Writer

1. Create pkg/writers/<format>/writer.go with NewWriter(options *writers.WriterOptions).
2. Implement writers.Writer: WriteDatabase, WriteSchema, WriteTable.
3. Add writer_test.go in the same package.
4. Register the format in the CLI switches.
5. Add a README.md in the writer directory.

Code Rules

• Format with gofumpt/goimports (make fmt); make check must pass.
• Iterate Table.Columns, Constraints, Indexes, Relationships in sorted order (maps are unordered; output must be deterministic).
• Every writer stamps buildinfo.GeneratedComment() in its file header.
• Comment exported functions and types.

Testing

• Tests live in the same package as the code.
• Table-driven tests; cover positive and negative cases.
• Reuse existing test data in tests/ and examples/ before adding new data.
• Tests run with -race.

Commits

• Format: type(scope): description
• Types: feat, fix, docs, test, refactor, chore, ci
• Keep commits focused. Reference issues where applicable.

Pull Requests

1. Branch from master.
2. Add tests; make test and make check pass.
3. Update docs/README if behaviour changes.
4. Open a PR with a clear description.

Security

Do not report vulnerabilities in public issues. See SECURITY.md.

License

Contributions are licensed under the Apache License 2.0.