Skip to content

RELEASE_PROCESS.md

Latest commit

 

History

History
80 lines (53 loc) · 2.96 KB

RELEASE_PROCESS.md

File metadata and controls

80 lines (53 loc) · 2.96 KB

Release Process

1. Prepare

Bump @version in mix.exs, update CHANGELOG.md, run tests, then commit and push to main:

# Confirm clean
mix test && cd native/ecto_libsql && cargo test && cd ../..
mix format --check-formatted && cd native/ecto_libsql && cargo fmt --check && cd ../..

git add mix.exs CHANGELOG.md
git commit -m "chore: bump version to X.Y.Z"
git push

2. Create the GitHub release (triggers CI)

The CI workflow triggers on tags matching *.*.*. The tag must match the version in mix.exs exactly - no v prefix, as the base_url in native.ex uses the raw version string.

gh release create X.Y.Z --title "vX.Y.Z" --draft --generate-notes

This creates the tag and a draft release simultaneously. gh release create --draft pushes the tag immediately (draft only controls public visibility), which fires the CI on: push: tags: trigger. CI builds all 6 NIF targets and uploads each artefact to the draft release via gh release upload.

Order matters: the draft release must be created before (or at the same time as) the tag. If you push the tag separately first, CI fires but fails at the upload step because no release exists yet to attach artefacts to.

3. Wait for all CI jobs to finish

gh run list --workflow=release.yml

All 6 matrix jobs must succeed:

  • aarch64-apple-darwin, x86_64-apple-darwin
  • aarch64-unknown-linux-gnu, aarch64-unknown-linux-musl
  • x86_64-unknown-linux-gnu, x86_64-unknown-linux-musl

4. Regenerate the checksum file

Once all artefacts are uploaded to the release:

MIX_ENV=prod mix rustler_precompiled.download EctoLibSql.Native --all --ignore-unavailable --no-config

This downloads every artefact from the GitHub release and regenerates checksum-Elixir.EctoLibSql.Native.exs. Verify the file has all 6 entries with fresh sha256 hashes.

5. Commit and push the checksum

git add checksum-Elixir.EctoLibSql.Native.exs
git commit -m "chore: update checksums for vX.Y.Z"
git push

This step is critical - the checksum file must be in the package so Hex.pm users can verify the downloaded NIFs.

6. Publish the GitHub release

gh release edit X.Y.Z --draft=false

7. Publish to Hex.pm

mix hex.publish

Key Gotchas

  • Tag format: Use 0.9.1 not v0.9.1 - the base_url in native.ex is releases/download/#{version}, so the tag and version must match exactly.
  • Checksum before publish: Always regenerate and commit the checksum file before mix hex.publish. Without it, users get integrity errors when installing.
  • --ignore-unavailable: Use with caution - only after confirming all 6 CI target builds have succeeded and all 6 release artefacts are present; otherwise it can mask missing binaries.
  • Test run option: The workflow_dispatch trigger on the release workflow has a test_only input that skips the gh release upload step, useful for testing the build matrix without creating a real release.