Release

Release torchft

This process publishes the stable torchft package to PyPI and creates a matching GitHub release. Nightly releases use the torchft-nightly package.

Access

The releaser needs:

1. Owner or maintainer access to the torchft PyPI project.
2. A local project-scoped PyPI token available to Twine.
3. Permission to create tags and releases in meta-pytorch/torchft.

Never reuse the nightly token for stable releases or print a token in shell history or logs.

Prepare

1. Confirm main is current and required CI is green.
2. Choose the next PEP 440 version. Use semantic versioning: patch for compatible fixes, minor for new or breaking pre-1.0 behavior, and major after 1.0.
3. Update the version in Cargo.toml.
4. If dependency support changed, update requires-python in pyproject.toml.
5. Open and merge a release PR. Its test plan must include unit tests, Rust tests, lint, package build, and twine check.

Before merging, verify locally:

uv venv --python 3.12 --managed-python
uv pip install -e '.[dev]'
uv run pytest -v --reruns 3 --reruns-delay 5
cargo test -v
cargo +nightly fmt --check
docker build --progress=plain -t torchft-maturin .
docker run --rm -v "$(pwd):/io" -t torchft-maturin build --release --out dist --interpreter 3.12
uvx --python 3.13 --from twine twine check --strict dist/*

Build

After the release PR is on main, use a clean checkout of that commit:

VERSION=0.2.0
git switch main
git pull --ff-only
test "$(sed -n 's/^version = "\([^"]*\)"/\1/p' Cargo.toml | head -1)" = "$VERSION"
test -z "$(git status --porcelain)"
test ! -e dist
docker build --progress=plain -t torchft-maturin .
docker run --rm -v "$(pwd):/io" -t torchft-maturin sdist --out dist
for python in 3.9 3.10 3.11 3.12 3.13; do
  docker run --rm -v "$(pwd):/io" -t torchft-maturin build --release --out dist --interpreter "$python"
done
uvx --python 3.13 --from twine twine check --strict dist/*

Inspect filenames and metadata before the irreversible upload:

ls -lh dist/
unzip -p "dist/torchft-${VERSION}-cp312-"*.whl "torchft-${VERSION}.dist-info/METADATA" | sed -n '1,40p'

Publish

git tag -a "v$VERSION" -m "torchft $VERSION"
git push origin "v$VERSION"
uvx --python 3.13 --from twine twine upload --skip-existing dist/*
gh release create "v$VERSION" dist/* --repo meta-pytorch/torchft --generate-notes --verify-tag --title "torchft $VERSION"

--skip-existing makes an upload retry safe after a partial failure. Never reuse a version for changed files.

Verify

1. Check the PyPI release and GitHub releases.

2. Install from PyPI in a clean environment:

   VERSION=0.2.0
   uv venv /tmp/torchft-release-check --python 3.12 --managed-python
   uv pip install --python /tmp/torchft-release-check/bin/python "torchft==$VERSION"
   uv run --no-project --python /tmp/torchft-release-check/bin/python python -c 'import torchft; print(torchft.__file__)'

3. Run torchft_lighthouse --help from that environment.

4. Confirm the release notes and attached files match the PyPI version.

Bad release

PyPI files and versions are immutable. Do not overwrite them. Yank a broken release in PyPI, fix forward with a new patch version, and mark the GitHub release as withdrawn. Rotate PYPI_TOKEN immediately if it may have leaked.