From 6f6b9834ca03c0b13f462bb2a2e4e46bfa475d87 Mon Sep 17 00:00:00 2001 From: Hein Date: Fri, 2 Oct 2026 23:29:25 +0200 Subject: [PATCH] docs(CONTRIBUTING): update setup instructions and add make targets --- CONTRIBUTING.md | 172 +++++++++++++++++------------------------------- SECURITY.md | 12 ++++ TODO.md | 29 +++++--- 3 files changed, 91 insertions(+), 122 deletions(-) create mode 100644 SECURITY.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7f0c249..d7b4910 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,145 +1,91 @@ # Contributing to RelSpec -Thank you for your interest in contributing to RelSpec. +## Setup -## Development Setup +- Go 1.25+ (see `go.mod`), Git +- Optional: golangci-lint, Docker/Podman (PostgreSQL integration tests) -### Prerequisites -- Go 1.21 or higher -- Git -- (Optional) golangci-lint for linting -- (Optional) Docker for database testing - -### Getting Started - -1. Clone the repository: ```bash -git clone https://github.com/wdevs/relspecgo.git +git clone git@git.warky.dev:wdevs/relspecgo.git cd relspecgo +make deps +make build # outputs build/relspec ``` -2. Install dependencies: -```bash -go mod download -``` +## Make Targets -3. Run tests: -```bash -go test ./... -``` +| 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 | -4. Build the project: -```bash -go build -o relspec ./cmd/relspec -``` +Single test: `go test -run TestName ./pkg/readers/dbml` -## Project Structure +## Layout ``` -relspecgo/ -├── cmd/ # CLI application entry point -├── pkg/ -│ ├── readers/ # Input format readers (XML, JSON, DCTX, DB, GORM, Bun) -│ ├── writers/ # Output format writers (GORM, Bun, JSON, YAML) -│ ├── models/ # Internal data models for relations -│ └── transform/ # Transformation and validation logic -├── examples/ # Usage examples and sample files -├── tests/ # Integration tests -└── .claude/ # Claude Code configuration and commands +cmd/relspec/ CLI commands (convert, diff, merge, split, edit, inspect, job, ...) +pkg/models/ Core model: Database > Schema > Table > Column/Constraint/Index/Relationship +pkg/readers/ One reader per format +pkg/writers/ 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 New Readers +## Adding a Reader -To add a new input format reader: +1. Create `pkg/readers//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. -1. Create a new file in `pkg/readers/` (e.g., `myformat_reader.go`) -2. Implement the `Reader` interface: -```go -type Reader interface { - Read(source string) (*models.Schema, error) -} -``` -3. Add tests in `pkg/readers/myformat_reader_test.go` -4. Register the reader in the CLI +## Adding a Writer -## Adding New Writers +1. Create `pkg/writers//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. -To add a new output format writer: +## Code Rules -1. Create a new file in `pkg/writers/` (e.g., `myformat_writer.go`) -2. Implement the `Writer` interface: -```go -type Writer interface { - Write(schema *models.Schema, destination string) error -} -``` -3. Add tests in `pkg/writers/myformat_writer_test.go` -4. Register the writer in the CLI - -## Code Style - -- Follow standard Go conventions -- Use `gofmt` for formatting -- Run `go vet` to check for issues -- Use meaningful variable and function names -- Add comments for exported functions and types +- 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 -- Write unit tests for all new functionality -- Aim for >80% code coverage -- Use table-driven tests where appropriate -- Include both positive and negative test cases +- 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`. -### Running Tests +## Commits -```bash -# All tests -go test ./... +- Format: `type(scope): description` +- Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`, `ci` +- Keep commits focused. Reference issues where applicable. -# With coverage -go test -cover ./... +## Pull Requests -# Verbose output -go test -v ./... +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. -# Specific package -go test ./pkg/readers/... -``` +## Security -## Committing Changes - -- Write clear, descriptive commit messages -- Follow conventional commits format: `type(scope): description` - - Types: feat, fix, docs, test, refactor, chore - - Example: `feat(readers): add PostgreSQL support` -- Keep commits focused and atomic -- Reference issues in commit messages when applicable - -## Pull Request Process - -1. Create a feature branch from `master` -2. Make your changes -3. Add tests for new functionality -4. Ensure all tests pass -5. Update documentation if needed -6. Submit a pull request with a clear description - -## Claude Code Commands - -This project includes Claude Code slash commands for common tasks: - -- `/test` - Run all tests -- `/build` - Build the binary -- `/lint` - Run linters -- `/coverage` - Generate coverage report - -## Questions or Issues? - -- Open an issue for bugs or feature requests -- Start a discussion for questions or ideas -- Check existing issues before creating new ones +Do not report vulnerabilities in public issues. See [SECURITY.md](SECURITY.md). ## License -By contributing to RelSpec, you agree that your contributions will be licensed under the Apache License 2.0. +Contributions are licensed under the Apache License 2.0. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..bb689fa --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,12 @@ +# Security Policy + +## Supported versions +Security fixes are released for the latest minor version of RelSpec. + +## Reporting a vulnerability +Please do not open a public issue for security problems. + +Report privately by email: warkydevs@gmail.com + +Reports are reviewed on a best-effort basis. No response time or fix timeline is +guaranteed. Reporters may be credited in the release notes if they wish. diff --git a/TODO.md b/TODO.md index beb7bc7..2ff3b7c 100644 --- a/TODO.md +++ b/TODO.md @@ -4,20 +4,25 @@ - [✔️] **Database Inspector** - [✔️] PostgreSQL driver (reader + writer) - - [ ] MySQL driver + - [ ] MySQL driver (only MariaDB datatype conversion in pkg/mariadb, no reader/writer) - [✔️] SQLite driver (reader + writer with automatic schema flattening) - - [ ] MSSQL driver + - [✔️] MSSQL driver (reader + writer, generated and identity columns) - [✔️] Foreign key detection - [✔️] Index extraction - [✔️] .sql file generation (PostgreSQL, SQLite) - [✔️] .dbml: Database Markup Language (DBML) for textual schema representation. - [✔️] Prisma schema support (PSL format) .prisma +- [ ] Sequelize (Typescript/Javascript) (Use templates, 💲 Someone can do this, not me) - [✔️] Drizzle ORM support .ts (TypeScript / JavaScript) (Mr. Edd wanted to move from Prisma to Drizzle. If you are bugs, you are welcome to do pull requests or issues) - [☠️] Entity Framework (.NET) model .edmx (Fuck no, EDMX files were bloated, verbose XML nightmares—hard to merge, error-prone, and a pain in teams. Microsoft wisely ditched them in EF Core for code-first. Classic overkill from old MS era.) - [✔️] TypeORM support -- [] .hbm.xml / schema.xml: Hibernate/Propel mappings (Java/PHP) (💲 Someone can do this, not me) -- [ ] Django models.py (Python classes), Sequelize migrations (JS) (💲 Someone can do this, not me) -- [] .avsc: Avro schema (JSON format for data serialization) (💲 Someone can do this, not me) +- [ ] .hbm.xml / schema.xml: Hibernate/Propel mappings (Java/PHP) (Use templates, 💲 Someone can do this, not me) +- [ ] Django models.py (Python classes), Sequelize migrations (JS) (Use templates, 💲 Someone can do this, not me) +- [ ] SQLAlchemy, Python (Use templates, 💲 Someone can do this, not me) +- [ ] .avsc: Avro schema (JSON format for data serialization) (Use templates, 💲 Someone can do this, not me) +- [ ] Rails schema in db/schema.rb (Use templates, 💲 Someone can do this, not me) +- [ ] Laravel migration (Use templates, 💲 Someone can do this, not me) +- [ ] Hibernate / JPA (Use templates, 💲 Someone can do this, not me) - [✔️] GraphQL schema generation ## UI @@ -39,13 +44,19 @@ ## Advanced Features -- [ ] Dry-run mode for validation -- [x] Diff tool for comparing specifications -- [ ] Migration script generation +- [ ] Dry-run mode for validation (only `job run --dry-run`; not on convert/merge/split) +- [✔️] Diff tool for comparing specifications +- [✔️] Migration script generation (PostgreSQL diff, live database by default for direct output) - [ ] Custom type mapping configuration -- [ ] Batch processing support +- [ ] Batch processing support (partial: job files run named workflows via `relspec job run`) - [ ] Watch mode for auto-regeneration +## Distribution + +- [ ] NSIS Windows installer + - [ ] Check https://git.warky.dev/wdevs/relspecgo/releases for new releases and prompt to update +- [ ] CI pipeline to build and publish the Windows installer + ## Future Considerations - [ ] Web UI for visual editing