Add git SHA to wheel versions using versioningit

[janbernloehr]

Adds automatic git SHA suffixing to wheel versions during development builds, matching the behavior of other PyTorch libraries (e.g., pytorch/ao).

Changes:

• Configured versioningit for automatic version generation from git tags
• Development builds now generate versions like: 0.2.0+gitf5e3a84e
• Tagged releases remain clean: 0.2.0

For releases: Versions are automatically determined from git tags (e.g., v0.2.0).

Build system: Adds versioningit>=3.3 to build requirements. No runtime dependencies added.

[meta-cla]

Hi @janbernloehr!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at [email protected]. Thanks!

[meta-cla]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!

[tianyu-l]

Thanks. Sorry that I'm not familiar with the stuff.

Could you share

• a comparison on what's the before & after behavior? Specifically what's the benefit?
• what's the full flow of doing a release after this change. Possibly also update https://github.com/pytorch/torchtitan/blob/main/docs/release.md?

[tianyu-l]

what's its relationship to assets/version.txt?

[janbernloehr]

Good point, that file would not be used anymore. As long as a git repo is available, the version will be derived from it. if we are on a tag, the tag is used, if not then the distance to the latest tag plus the short hash is used, e.g. 0.2.0.post77+gf5e3a84e (77 commits after v0.2.0 tag)

[tianyu-l]

where and when do we set this?

[janbernloehr]

you only set this if you want to override the default behavior. the default should be fine since releases are done on a tag.

[janbernloehr]

• a comparison on what's the before & after behavior? Specifically what's the benefit?

The before behavior is: if you build a wheel of torchtitan it will get the version of version.txt - irregardless of how many changes have been done. This makes it hard to distinguish development builds from release builds.
The after behavior is: Only when building on the commit of a tag, we get the version from the tag, e.g. v0.2.0. In all other cases, the version is derived by setuptools, e.g. 0.2.0.post77+gf5e3a84e (77 commits after v0.2.0 tag)

• what's the full flow of doing a release after this change. Possibly also update https://github.com/pytorch/torchtitan/blob/main/docs/release.md?

done

We can also choose a different mechanism to derive the version number. I chose setuptools_scm because it is somewhat standard and works well with the pyproject.toml. but e.g. pytorch, ao, and vision use a setup.py to compute the version and also get slightly different version suffixes (e.g. on 2.0.0 and commit b425c6f) one would get:

• torch: 2.0.0+gitb425c6f
• ao: 2.0.0+gitb425c6f
• vision: 2.0.0+b425c6f

[tianyu-l]

another noob question

This makes it hard to distinguish development builds from release builds.

What would a scenario when people need development builds, e.g. is torchtitan nightly build a "development build"?

[tianyu-l]

I'm still a bit puzzled.

The after behavior is: Only when building on the commit of a tag, we get the version from the tag, e.g. v0.2.0. In all other cases, the version is derived by setuptools

There are several places one can edit a version.

1. the file torchtitan/_version.py
2. create the tag with a version (e.g. v0.2.0) when you do https://github.com/pytorch/torchtitan/releases/new
3. In pyproject.toml, you mentioned "To override version for releases: set SETUPTOOLS_SCM_PRETEND_VERSION=x.y.z"

In the past, IIUC the version in tag and the version in version.txt are (somewhat?) independent, so we need to manually keep track.

[janbernloehr]

The file _version.py will be generated by setuptools_scm - so its content does not really matter. However, if git is not available, then it falls back to the version defined in this file.

So you can control the version either by creating a tag - or you overwrite it by exporting and envvar SETUPTOOLS_SCM_PRETEND_VERSION=x.y

In other cases, setuptools_scm will generate the version.

[janbernloehr]

You are right that is too confusing. Let us use versioningit instead of setuptools_scm which is significantly simpler:

• On a tag v0.2.0 you get 0.2.0
• On a commit after v0.2.0 you get 0.2.0+gitb425c6f

Similar to other torch libraries. Moreover, in CI there is .github/scripts/update_version.sh which is called with BUILD_VERSION set externally. I made sure that this still works and uses the externally provided version.

[tianyu-l]

@janbernloehr
change LGTM, glad that I pushed :)

How do we verify this works? Would you be able to demonstrate this in the fork? i.e. create a new release and observe automatically updated tag?

[janbernloehr]

What I did to test it was

Run uv build --wheel . on the branch as is:

Successfully built dist/torchtitan-0.2.0+gita53b69fc-py3-none-any.whl

Create new tag v0.3.0 and run uv build --wheel .

Successfully built dist/torchtitan-0.3.0-py3-none-any.whl

Run BUILD_VERSION=0.1.0.dev20251022+cpu bash .github/scripts/update_version.sh

Successfully built dist/torchtitan-0.1.0.dev20250921+cpu-py3-none-any.whl

I have also created a "fake" release v0.3.0 on my fork: https://github.com/janbernloehr/torchtitan/actions/runs/19601607282/job/56133915316#step:4:1005

Successfully built torchtitan-0.3.0.tar.gz and torchtitan-0.3.0-py3-none-any.whl

[tianyu-l]

LGTM, will let @joecummings take a final look before merge.

[fegin]

Thanks for the PR. I feel we can remove .github/scripts/update_version.sh and just use importlib.metadata to get the version. But this is orthogonal to this PR.

[tianyu-l]

I feel we can remove .github/scripts/update_version.sh and just use importlib.metadata to get the version. But this is orthogonal to this PR.

so context is that update_version.sh is for producing nightly. So not sure if / how it can be saved. @joecummings who added the file may know how.

[fegin]

If one install TorchTitan package correctly, the version should be in metadata. And since this PR make version to be dynamic, it will automatically reflect the latest version with git SHA.

[joecummings]

Removing the version.txt file will break any builds intending to use the PyTorch Dev Infra build system and since this isn't urgent, I'd like to not merge quite yet.

I know there's been changes to how Dev Infra wants to continue these workflows so let me get @seemethere's thoughts as well. Will update on this thread by EOD today.

[joecummings]

Removing the version.txt file will break any builds intending to use the PyTorch Dev Infra build system and since this isn't urgent, I'd like to not merge quite yet.

I know there's been changes to how Dev Infra wants to continue these workflows so let me get @seemethere's thoughts as well. Will update on this thread by EOD today.

@atalman It looks like we could pass in an override to the nightly package here. Am I understanding correctly? If so, does it make sense to bubble up to the top level build script?

I'm also curious in general if continuing to hack on these Nova workflows is the right way to go to do these nightly builds?