Releasing subtr-actor

This document describes how to release new versions of subtr-actor to GitHub Releases, crates.io, PyPI, and npm.

Overview

The project publishes five packages:

• Rust: subtr-actor on crates.io
• Python: subtr-actor-py on PyPI
• JavaScript bindings: @rlrml/subtr-actor on npm
• JavaScript player: @rlrml/player on npm
• JavaScript stats player: @rlrml/stats-player on npm

Automated Releases (GitHub Actions)

When you push a tag starting with v (for example, v<version>), the following workflows run automatically:

GitHub (release-github.yml)

Creates or updates the GitHub Release page for the tag using the matching section from CHANGELOG.md.

Rust (release-rust.yml)

Publishes the Rust crate to crates.io.

Python (release-python.yml)

Builds wheels for multiple platforms:

• Linux x86_64 (manylinux) - compatible with AWS Lambda, Docker, etc.
• Linux aarch64 (ARM)
• Windows x86_64
• macOS x86_64 and arm64
• Source distribution (sdist)

All artifacts are published to PyPI.

JavaScript (release-js.yml)

Builds the WebAssembly bindings package, builds the player package, smoke-tests the packed player artifact in a fresh consumer app, builds the stats player package, smoke-tests that packed artifact in a fresh consumer app, and publishes all three npm packages.

Setup Required (One-Time)

PyPI Publishing

Option A: Trusted Publishing (Recommended)

1. Go to PyPI → Account Settings → Publishing
2. Add a new pending publisher:
   • Owner: rlrml
   • Repository: subtr-actor
   • Workflow: release-python.yml
   • Environment: pypi

Option B: API Token

1. Create a PyPI API token at https://pypi.org/manage/account/token/
2. Add it as a GitHub secret named PYPI_TOKEN
3. Update the workflow to use the token instead of trusted publishing

npm Publishing

1. Create an npm access token at https://www.npmjs.com/settings/~/tokens
2. Add it as a GitHub secret named NPM_TOKEN

How to Release

1. Update Version Numbers

Set the Cargo workspace version and synchronize every duplicated release metadata file from that source of truth:

VERSION=${VERSION:?set VERSION to the target release}
python3 scripts/sync_release_versions.py "$VERSION"
python3 scripts/check_release_versions.py

Or use the justfile helper:

VERSION=${VERSION:?set VERSION to the target release}
just bump "$VERSION"

2. Commit and Tag

VERSION=${VERSION:?set VERSION to the target release}
git add -A
git commit -m "Release v$VERSION"
git tag "v$VERSION"
git push origin master --tags

3. Monitor the Release

• Go to the repository's Actions tab
• Watch the Release GitHub, Release Rust, Release Python, and Release JavaScript workflows
• Once complete, verify packages are available:
  • https://github.com/rlrml/subtr-actor/releases
  • https://crates.io/crates/subtr-actor
  • https://pypi.org/project/subtr-actor-py/
  • https://www.npmjs.com/package/@rlrml/subtr-actor
  • https://www.npmjs.com/package/@rlrml/player
  • https://www.npmjs.com/package/@rlrml/stats-player

Manual Release (Alternative)

If you need to release manually:

Python

cd python
maturin build --release
twine upload target/wheels/*

JavaScript

cd js
wasm-pack build --target bundler --out-dir pkg
cd pkg && npm publish --access public

cd ../player
package_dir="$(npm run --silent prepare:package)"
(cd "$package_dir" && npm publish --access public)

cd ../stat-evaluation-player
package_dir="$(npm run --silent prepare:package)"
(cd "$package_dir" && npm publish --access public)

Troubleshooting

Python wheel build fails

• Ensure Rust toolchain is installed
• Check maturin version compatibility in pyproject.toml

Linux wheel missing

• The manylinux: auto setting should produce compatible wheels
• If issues persist, try manylinux: 2014 or manylinux: 2_28

npm publish fails

• Verify NPM_TOKEN secret is set
• Check that the package name isn't taken
• Ensure version number is incremented