RELEASE

Copy Markdown View Source

name: release description: | Covers: Version bump workflow, GitHub tagging, GitHub releases, and Hex publishing. Consult when: Cutting a new kagi_ex release, bumping @version, or recovering a failed release. Not covered: Day-to-day development (see README.md), CI implementation details (see .github/workflows/*.yml).

Release

kagi_ex releases have two parts:

  1. GitHub tag and release
  2. Hex publication, with docs published automatically

Quick Reference

StepTriggerOutput
Bump @version in mix.exsPR to mainRelease candidate commit
Merge version bump to mainrelease.ymlvX.Y.Z tag and GitHub release
Publish packagemix hex.publishHex package and HexDocs docs

Version Bump Rules

  • Bump mix.exs @version only when that merge should create a release.
  • Update CHANGELOG.md in the same PR.
  • No version change means no tag and no GitHub release.

Automated GitHub Release

After the version-bump PR is merged to main:

  1. .github/workflows/release.yml compares the current mix.exs version with HEAD^.
  2. If the version changed, the workflow ensures vX.Y.Z exists.
  3. The same workflow publishes a GitHub release for vX.Y.Z.

Use the workflow's manual dispatch only to re-run a release for the current version tag after fixing workflow issues.

Exact Hex Release Steps

Run these steps only after the GitHub release for the same version exists.

1. Refresh local checkout after the GitHub release workflow finishes

jj git fetch
jj rebase -o main

2. Verify the package from the exact publishing tree

mix hex.build
mix docs

3. Publish the package

mix hex.publish

Gotchas

  • Do not publish to Hex before the matching GitHub release exists.
  • Do not reuse versions. Hex versions are immutable.
  • mix hex.publish publishes documentation automatically.