Skip to content

Contributing

go-compressions follows the same conventions as the author's other Go organizations.

Hard rules

  • Pure Go, CGO_ENABLED=0, across the org. No cgo bindings, no native shims. cgo wrappers of the C references are faster still but out of scope — this is the pure-Go tier.
  • Wire-compatible or nothing. A codec must interoperate byte-for-byte with the canonical reference it implements: data from the reference must decode here, and data produced here must decode under the reference. A hash must be bit-identical to the official test vectors on every code path.
  • SIMD behind build tags, never at the cost of correctness. Accelerated kernels (e.g. matchlen's common-prefix loop, blake3's mix4) are generated by go-asmgen and are bit-identical to the scalar fallback, which always exists so the package builds and is correct on every GOARCH.
  • 100% statement coverage of the Go code, enforced as a CI gate. Every dispatch branch (each SIMD path and the scalar fallback) is driven by a force test on the native runner.
  • Honest numbers. Report wins, parities, and the cases where this code trails the state of the art alike. Headline benchmarks come from native runs, never from emulation; ppc64le is now natively measured on real POWER10 silicon and riscv64 on a real SpacemiT X60 (RVV 1.0, a low-power in-order core — the only widely-available RVV silicon; GCC Compile Farm), while s390x stays correctness-validated with native perf pending an IBM Z runner. Six SIMD targets, validated on seven architectures (the seventh, ppc64 big-endian, is build + test validated on real POWER9).
  • English only for all repository content (issues, PRs, commits, comments).

Adding or changing a codec / hash

  1. Pin the reference (see methodology) and decide the compatibility contract — which magics/headers, which modes.
  2. Implement the pure-Go path first. It must be correct and portable before any SIMD is added.
  3. Prove compatibility and safety with a round-trip / differential fuzz target against the reference and a corruption fuzz target asserting no-panic on garbage input.
  4. Add SIMD only where it earns its place — drive go-asmgen to emit the kernel, commit the generated .s, and add a force test for each dispatch branch. Verify bit-identical to scalar.
  5. Validate on real hardware — native arm64 for headline throughput, amd64 cross-check for byte-identical output, native ppc64le (POWER10) for measured VSX throughput, native riscv64 (SpacemiT X60, RVV 1.0) for measured RVV throughput, s390x under QEMU for correctness, and ppc64 big-endian (POWER9) for build + test validation of the portable fallback path.
  6. Confirm 100% coverage: 
    go test -coverprofile=cover.out ./...
go tool cover -func=cover.out   # must read 100.0%

Documentation

This site is built with MkDocs Material and versioned with mike; see the docs repo README for local preview and release commands. The organization landing page lives in go-compressions.github.io (Hugo).