Contributing

Contributing & Releases

Development

make check   # fmt, vet, lint and test — everything CI runs
make test    # tests with the race detector and -shuffle=on
make cover   # coverage profile and HTML report
make bench   # benchmarks
make fuzz    # every fuzz target
make lint    # golangci-lint
make help    # list all targets

Before opening a PR: gofmt, go vet ./... and make test must be clean, and new behavior needs tests. Follow Conventional Commits.

House rules

• No dependencies. The module deliberately has none, and CI fails if go.sum ever appears. Anything needed goes in the repository or in internal/.
• Tests must not depend on order. CI runs go test -shuffle=on; do not share mutable state between tests.
• Document exported identifiers. revive enforces this.
• Data changes need a source. See Data sources.

What CI runs

Build, vet and test on Go 1.22–1.26 on Linux, plus macOS and Windows on the newest; a gofmt gate and golangci-lint; a 20-second run of every fuzz target; a container build with a smoke test; and govulncheck.

Releases

Push a semantic-version tag:

git tag v1.2.3
git push origin v1.2.3

The release workflow tests, builds the CLI for six platforms with checksums, publishes the GitHub release and the container image, and warms the Go module proxy so the version appears on pkg.go.dev.

Third-party actions are pinned to commit SHAs and kept current by Renovate and Dependabot.

Security

Report security issues privately to the maintainers — do not open a public issue. See SECURITY.md.