# Contributing to RelSpec

## Setup

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

```bash
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](SECURITY.md).

## License

Contributions are licensed under the Apache License 2.0.