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