92 lines
3.2 KiB
Markdown
92 lines
3.2 KiB
Markdown
# 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.
|