---
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

| Step                         | Trigger           | Output                          |
| ---------------------------- | ----------------- | ------------------------------- |
| Bump `@version` in `mix.exs` | PR to `main`      | Release candidate commit        |
| Merge version bump to `main` | `release.yml`     | `vX.Y.Z` tag and GitHub release |
| Publish package              | `mix hex.publish` | Hex package and HexDocs docs    |

## Version Bump Rules

- Bump [mix.exs](mix.exs) `@version` only when that merge should create a release.
- Update [CHANGELOG.md](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

```bash
jj git fetch
jj rebase -o main
```

### 2. Verify the package from the exact publishing tree

```bash
mix hex.build
mix docs
```

### 3. Publish the package

```bash
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.