# Release

> How to prepare and publish GitHub releases for prime-rl. Use when drafting release notes, tagging versions, or publishing releases.

- Skill: `mixedbread-ai/release` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mixedbread-ai/release`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mixedbread-ai/release/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mixedbread-ai (https://skillmd.com/u/mixedbread-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mixedbread-ai/release

---


# Releases

Releases are driven by [`.github/workflows/tag-and-release.yaml`](../../.github/workflows/tag-and-release.yaml). The flow:

1. You create a **draft GitHub Release** with the notes inline (`gh release create --draft`).
2. You open a **draft PR** that bumps `version` in `pyproject.toml`.
3. Maintainer merges. The workflow tags the commit, builds the `prime-kernels` wheels and
   attaches them to the draft, then promotes it.

Release notes live on the GitHub Release, not in the repo. Prime-rl is **not** on PyPI. `.dev` tags are handled separately by `devx_tag.yaml`; `tag-and-release.yaml` ignores them.

## 1. Decide the version

```bash
git fetch origin --tags
grep '^version' pyproject.toml
gh release list --repo PrimeIntellect-ai/prime-rl --limit 5
```

SemVer (`MAJOR.MINOR.PATCH`). Confirm with the user before continuing.

## 2. Draft the notes

Match the prior release's structure: numbered highlights (`# 1.`, ...), then `# Breaking Changes`, `# Bug Fixes`, `# Misc`, `# Contributors`. Use `##` subsections inside a highlight when it bundles multiple items.

```bash
PREV=$(gh release list --limit 1 --json tagName --jq '.[0].tagName')
gh release view "$PREV" --json body --jq .body          # style reference
git log "$PREV"..origin/main --oneline --no-merges      # commits since
gh pr list --base main --state merged --search \
  "merged:>=$(gh release view "$PREV" --json publishedAt --jq .publishedAt)" \
  --limit 500 --json number,title,author                # for PR links + contributors
```

Tips:
- PR refs: `[#1234](https://github.com/PrimeIntellect-ai/prime-rl/pull/1234)`.
- Contributors: order by commit count, use the GH `@username` from the API (not git author names).
- Verify any TOML field names against the actual config classes.

## 3. Create the draft release

```bash
NEW=v0.6.0
gh release create --draft "$NEW" --title "$NEW" --target main --notes-file /tmp/release-notes-$NEW.md
gh release view "$NEW" --json isDraft,tagName --jq '{tagName, isDraft}'   # expect isDraft: true
```

Iterate with `gh release edit "$NEW" --notes-file /tmp/release-notes-$NEW.md`.

## 4. Open the version-bump PR

```bash
git switch -c chore/release-$NEW
# bump `version = "..."` in pyproject.toml
git add pyproject.toml
git commit -m "chore: release $NEW"
git push -u origin "chore/release-$NEW"
gh pr create --draft --title "chore: release $NEW" --body "Bumps version to ${NEW#v}. Draft release: https://github.com/PrimeIntellect-ai/prime-rl/releases/tag/$NEW"
```

Stop. Do not tag, push tags, or flip the draft to published — the workflow does that on merge.

## 5. After it publishes: move the kernel pin

The release now carries `prime_kernels-*.whl` for x86_64 and aarch64. Point installs at them
so nobody compiles CUDA, in a follow-up PR:

```bash
gh release view "$NEW" --json assets --jq '.assets[].name'   # exact filenames, ABI and all
```

Update the `prime-kernels` URLs under `[tool.uv.sources]` in `pyproject.toml` to `$NEW`, then
`uv sync --all-extras` to relock. The pin always trails one release — `$NEW`'s wheels do not
exist until `$NEW` is built. See the `kernels` skill.

## Recovery

If the workflow tagged the commit but failed to promote the draft, the next main push (or `workflow_dispatch` with `tag: v{new}`) re-promotes it. A rerun rebuilds and re-uploads the kernel wheels (`--clobber`), which is harmless.