107 lines
2.5 KiB
Markdown
107 lines
2.5 KiB
Markdown
# Development
|
|
|
|
## Requirements
|
|
|
|
- Go 1.24 or later
|
|
|
|
## Setup
|
|
|
|
```sh
|
|
git clone https://git.rumginger.org/agent/dataxl.git
|
|
cd dataxl
|
|
go mod download
|
|
```
|
|
|
|
## Common Commands
|
|
|
|
Format code:
|
|
|
|
```sh
|
|
gofmt -w cmd/dataxl/*.go
|
|
```
|
|
|
|
Run tests:
|
|
|
|
```sh
|
|
go test ./...
|
|
```
|
|
|
|
Build:
|
|
|
|
```sh
|
|
go build ./cmd/dataxl
|
|
```
|
|
|
|
Run locally:
|
|
|
|
```sh
|
|
go run ./cmd/dataxl -from yaml -to tsv -i examples/people.yaml
|
|
```
|
|
|
|
Build release archives locally:
|
|
|
|
```sh
|
|
scripts/build-release.sh
|
|
```
|
|
|
|
## Test Coverage
|
|
|
|
The current tests cover:
|
|
|
|
- YAML -> TSV flattening
|
|
- TSV -> JSON path restoration
|
|
- JSON -> XLSX -> JSON round trip
|
|
- structured -> structured conversion without CLI/file I/O
|
|
- extension normalization and format inference
|
|
- ragged table row padding
|
|
- conservative cell type inference, including zero-padded identifiers
|
|
- conflicting unflatten paths
|
|
|
|
When adding a new format or path rule, add tests around both directions where
|
|
possible.
|
|
|
|
## CI/CD
|
|
|
|
Gitea Actions workflows live under `.gitea/workflows`.
|
|
|
|
- `ci.yml`: runs on pushes to `main`, pull requests, and manual dispatch.
|
|
- `release.yml`: runs on `v*` tag pushes and manual dispatch with a `tag` input.
|
|
|
|
The CI workflow checks formatting, runs tests, builds the CLI, and performs a
|
|
small YAML -> TSV -> JSON smoke test.
|
|
|
|
The release workflow runs tests, cross-builds release archives for Linux,
|
|
macOS, and Windows on amd64/arm64, writes `checksums.txt`, creates or reuses a
|
|
Gitea Release, and uploads the generated assets. It uses the built-in
|
|
`${{ secrets.GITEA_TOKEN }}` provided by Gitea Actions.
|
|
|
|
## Release Notes
|
|
|
|
Create a release by pushing a version tag:
|
|
|
|
```sh
|
|
go test ./...
|
|
git tag v0.1.0
|
|
git push origin main --tags
|
|
```
|
|
|
|
The same workflow can also be started manually from Gitea Actions by providing
|
|
the target tag as the `tag` input.
|
|
|
|
After tags exist, users can install a specific version:
|
|
|
|
```sh
|
|
go install git.rumginger.org/agent/dataxl/cmd/dataxl@v0.1.0
|
|
```
|
|
|
|
## Design Guidelines
|
|
|
|
- Keep stdin/stdout usable for shell pipelines.
|
|
- Keep TSV behavior predictable because it is the main Excel clipboard format.
|
|
- Preserve headers as the contract between spreadsheet data and structured data.
|
|
- Prefer explicit errors over silent best-effort conversion when a format is unsupported.
|
|
- Keep dependencies small unless a format needs a mature parser/writer.
|
|
- Keep CLI/file I/O in `main.go`; conversion behavior should remain testable through `convert`.
|
|
- Keep format-specific behavior in its structured or table adapter.
|
|
- Document round-trip limitations when a representation cannot preserve a value exactly.
|