Go Binding Release Checklist

Use this checklist when publishing the Go module at:

github.com/apache/paimon-rust/bindings/go

Tagging Strategy

  • Choose a reviewed Rust release baseline commit first.
  • That baseline usually corresponds to the Rust source release tag or an approved release-candidate commit.
  • Build the Go binding release artifacts from that baseline.
  • Because the Go module embeds generated shared-library archives, bindings/go/vX.Y.Z does not need to point to the exact same commit as the Rust release tag.
  • Instead, bindings/go/vX.Y.Z may point to a follow-up repository commit that adds only Go release assets under bindings/go/.

In practice, the release relationship should look like this:

  1. pick a Rust release baseline commit,
  2. create the Rust release tag from that baseline when appropriate,
  3. build the Go embedded libraries from the same baseline,
  4. create a Go release commit that contains the generated libpaimon_c.*.zst files, and
  5. tag that commit as bindings/go/vX.Y.Z or bindings/go/vX.Y.Z-rc.N.

This keeps a clear link to the Rust release baseline while allowing the Go submodule tag to contain the embedded artifacts required by Go module consumers.

Recommended Sequence

  • For an ASF-style release process, first complete the source release steps for the Rust project.
  • After the corresponding release candidate has been approved, run the Go binding release workflow to publish the convenience Go module tag.
  • If you publish release candidates for the Go binding, base them on the same reviewed Rust release-candidate commit.

Before Release

  • Confirm the Go API changes are ready to publish.
  • Confirm the target version is decided, for example v0.1.0.
  • Confirm the Rust release baseline commit for this Go release is recorded.
  • Decide the exact source_ref to pass into the release workflow.
  • Confirm whether this Go release is based on a Rust GA tag or an approved Rust release-candidate commit.
  • Use vX.Y.Z-rc.N for release candidates, for example v0.1.0-rc.1.
  • Use vX.Y.Z for the final general-availability release.
  • Confirm the version has not already been used as a Go submodule tag: bindings/go/v0.1.0.
  • Confirm the Go binding still targets the correct module path in bindings/go/go.mod.
  • Confirm the embedded-library filenames expected by the Go package still match the Makefile output:
    • libpaimon_c.linux.amd64.so.zst
    • libpaimon_c.linux.arm64.so.zst
    • libpaimon_c.darwin.amd64.dylib.zst
    • libpaimon_c.darwin.arm64.dylib.zst
  • Confirm CI is green on main before publishing.

Publish

  • Open GitHub Actions and run Release Go Binding.
  • Provide the release version, for example v0.1.0.
  • Provide source_ref, for example main, v0.1.0-rc.1, or a specific commit SHA.
  • For release candidates, publish bindings/go/vX.Y.Z-rc.N first and verify it before the final tag.
  • Make sure the workflow is started from the intended Rust release baseline branch or commit lineage.
  • Wait for all matrix builds to finish successfully:
    • linux/amd64
    • linux/arm64
    • darwin/amd64
    • darwin/arm64
  • Confirm the workflow creates the annotated tag bindings/go/v0.1.0.
  • Confirm the workflow publishes a GitHub release for that tag.

After Release

  • Confirm the release contains all four compressed shared-library assets.
  • Confirm the tag resolves to a commit that contains:
    • bindings/go/go.mod
    • bindings/go/RELEASE.md
    • the four libpaimon_c.*.zst files
  • Record which Rust release tag or baseline commit this Go binding release was built from.
  • Verify module resolution from a clean environment:
go list -m github.com/apache/paimon-rust/bindings/go@v0.1.0
  • Verify install/import from a small test module:
go get github.com/apache/paimon-rust/bindings/go@v0.1.0

import paimon "github.com/apache/paimon-rust/bindings/go"
  • If module proxy indexing is slow, retry after a few minutes and verify again.

Rollback Notes

  • Do not reuse a broken Go module version once it has been observed externally.
  • Do not delete and recreate an existing bindings/go/vX.Y.Z-rc.N or bindings/go/vX.Y.Z tag.
  • Publish a new patch version instead, for example move from v0.1.0 to v0.1.1.
  • If an RC is bad, publish the next RC, for example move from v0.1.0-rc.1 to v0.1.0-rc.2.
  • If the workflow fails before pushing the tag, fix the issue and rerun with the same intended version.