mjlab/RELEASING.md

Releasing

Pre-release checklist

1. Bump version in pyproject.toml.
2. Update version and date-released in CITATION.cff.
3. Update the "Upcoming version (not yet released)" heading in docs/source/changelog.rst to the new version number and date.
4. Commit the version bump, then create an annotated tag:

git tag -a vX.Y.Z -m "Release vX.Y.Z"
git push origin vX.Y.Z

Build and verify

Clean previous build artifacts, then build:

rm -rf dist/
make build

This runs uv build to produce a wheel and sdist in dist/, then smoke-tests both artifacts in isolated environments.

Test on TestPyPI (optional but recommended)

Upload to TestPyPI first to catch packaging issues before the real release:

UV_PUBLISH_TOKEN=<your-testpypi-token> make publish-test

Then verify the upload works end-to-end. Use --index-strategy unsafe-best-match because TestPyPI won't have all dependencies and uv needs to fall back to real PyPI for them:

uvx --extra-index-url https://test.pypi.org/simple/ \
    --index-strategy unsafe-best-match \
    --from mjlab \
    demo

Note: TestPyPI requires a separate account and token from real PyPI. Generate one at https://test.pypi.org/manage/account/token/.

Publish to PyPI

UV_PUBLISH_TOKEN=<your-pypi-token> make publish

Generate a token at https://pypi.org/manage/account/token/.

Post-release

Verify the release installs and runs correctly. Use --refresh to bypass the uvx cache (which may still hold the TestPyPI version):

uvx --refresh --from mjlab demo

Releasing from a past tag

If the tag has already been created and HEAD has moved ahead, check out the tag before building:

git checkout vX.Y.Z
make build
make publish
git checkout main