wdevs/relspecgo
5
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Releases 83 Wiki Activity

docs(CONTRIBUTING): update setup instructions and add make targets

Browse Source
This commit is contained in:
warkanum
2026-10-02 23:29:25 +02:00
parent 9cc10715e3
commit 6f6b9834ca
3 changed files with 91 additions and 122 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+59 -113
View File
@@ -1,145 +1,91 @@
# Contributing to RelSpec # 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 ```bash
git clone https://github.com/wdevs/relspecgo.git git clone git@git.warky.dev:wdevs/relspecgo.git
cd relspecgo cd relspecgo
make deps
make build # outputs build/relspec
``` ```
2. Install dependencies: ## Make Targets
```bash
go mod download
```
3. Run tests: | Target | Purpose |
```bash |-------------------------|------------------------------------------------------|
go test ./... | `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: Single test: `go test -run TestName ./pkg/readers/dbml`
```bash
go build -o relspec ./cmd/relspec
```
## Project Structure ## Layout
``` ```
relspecgo/ cmd/relspec/ CLI commands (convert, diff, merge, split, edit, inspect, job, ...)
├── cmd/ # CLI application entry point pkg/models/ Core model: Database > Schema > Table > Column/Constraint/Index/Relationship
├── pkg/ pkg/readers/<fmt> One reader per format
│ ├── readers/ # Input format readers (XML, JSON, DCTX, DB, GORM, Bun) pkg/writers/<fmt> One writer per format
│ ├── writers/ # Output format writers (GORM, Bun, JSON, YAML) pkg/diff, merge, inspector, jobs, transform, ui, pgsql, sqltypes ...
│ ├── models/ # Internal data models for relations examples/ Sample files
│ └── transform/ # Transformation and validation logic tests/ Integration tests and assets
├── examples/ # Usage examples and sample files docs/ Feature docs
├── tests/ # Integration tests
└── .claude/ # Claude Code configuration and commands
``` ```
## Adding New Readers ## Adding a Reader
To add a new input format 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.
1. Create a new file in `pkg/readers/` (e.g., `myformat_reader.go`) ## Adding a Writer
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 New Writers 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.
To add a new output format writer: ## Code Rules
1. Create a new file in `pkg/writers/` (e.g., `myformat_writer.go`) - Format with gofumpt/goimports (`make fmt`); `make check` must pass.
2. Implement the `Writer` interface: - Iterate `Table.Columns`, `Constraints`, `Indexes`, `Relationships` in sorted order (maps are unordered; output must be deterministic).
```go - Every writer stamps `buildinfo.GeneratedComment()` in its file header.
type Writer interface { - Comment exported functions and types.
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
## Testing ## Testing
- Write unit tests for all new functionality - Tests live in the same package as the code.
- Aim for >80% code coverage - Table-driven tests; cover positive and negative cases.
- Use table-driven tests where appropriate - Reuse existing test data in `tests/` and `examples/` before adding new data.
- Include both positive and negative test cases - Tests run with `-race`.
### Running Tests ## Commits
```bash - Format: `type(scope): description`
# All tests - Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`, `ci`
go test ./... - Keep commits focused. Reference issues where applicable.
# With coverage ## Pull Requests
go test -cover ./...
# Verbose output 1. Branch from `master`.
go test -v ./... 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 ## Security
go test ./pkg/readers/...
```
## Committing Changes Do not report vulnerabilities in public issues. See [SECURITY.md](SECURITY.md).
- 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
## License ## 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.
SECURITY.md
+12
View File
@@ -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.
TODO.md
+20 -9
View File
@@ -4,20 +4,25 @@
- [✔️] **Database Inspector** - [✔️] **Database Inspector**
- [✔️] PostgreSQL driver (reader + writer) - [✔️] 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) - [✔️] SQLite driver (reader + writer with automatic schema flattening)
- [ ] MSSQL driver - [✔️] MSSQL driver (reader + writer, generated and identity columns)
- [✔️] Foreign key detection - [✔️] Foreign key detection
- [✔️] Index extraction - [✔️] Index extraction
- [✔️] .sql file generation (PostgreSQL, SQLite) - [✔️] .sql file generation (PostgreSQL, SQLite)
- [✔️] .dbml: Database Markup Language (DBML) for textual schema representation. - [✔️] .dbml: Database Markup Language (DBML) for textual schema representation.
- [✔️] Prisma schema support (PSL format) .prisma - [✔️] 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) - [✔️] 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.) - [☠️] 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 - [✔️] TypeORM support
- [] .hbm.xml / schema.xml: Hibernate/Propel mappings (Java/PHP) (💲 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) (💲 Someone can do this, not me) - [ ] Django models.py (Python classes), Sequelize migrations (JS) (Use templates, 💲 Someone can do this, not me)
- [] .avsc: Avro schema (JSON format for data serialization) (💲 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 - [✔️] GraphQL schema generation
## UI ## UI
@@ -39,13 +44,19 @@
## Advanced Features ## Advanced Features
- [ ] Dry-run mode for validation - [ ] Dry-run mode for validation (only `job run --dry-run`; not on convert/merge/split)
- [x] Diff tool for comparing specifications - [✔️] Diff tool for comparing specifications
- [ ] Migration script generation - [✔️] Migration script generation (PostgreSQL diff, live database by default for direct output)
- [ ] Custom type mapping configuration - [ ] 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 - [ ] 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 ## Future Considerations
- [ ] Web UI for visual editing - [ ] Web UI for visual editing