/release

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

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

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.

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

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

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:

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.