[RFC] New versioning scheme for IREE Python packages

[marbre]

Summary

Our pre-compiled software is currently made publicly available using different versioning schemes. We're proposing a new versioning scheme to remedy this situation to which downstream packages depending on IREE can easily adopt.

This affects these packages:

• https://pypi.org/project/iree-compiler/ (current version 20240828.999)
• https://pypi.org/project/iree-runtime/ (current version 20240828.999)
• https://pypi.org/project/iree-turbine/ (current version 2.4.1)
• (maybe) https://pypi.org/project/iree-tools-tflite/ (current version 20240226.813)
• (maybe) https://pypi.org/project/iree-tools-tf/ (current version 20240226.813)

Here are examples of the new versions we propose:

Type of build	Version format	Version example
Stable release (PyPI)	X.Y.Z	3.0.0
Nightly release (GitHub schedule)	X.Y.ZrcYYYYMMDD	3.0.1rc20241029
Dev release (GitHub pull_request)	X.Y.Z.devNN	3.0.1.dev50
Local build	X.Y.Z.dev	3.0.1.dev

Key

Identifier	Explanation
X	Major version
Y	Minor version
Z	Patch version
rc	release candidate (main branch)
dev	developer build (code on pull request branches)
YYYY	Year, e.g. 2024
MM	Month, e.g. 10
DD	Day, e.g. 29
NN	Build number (increasing ID from GitHub per workflow), e.g. 50

Background

Currently CalVer is used for releasing iree-compiler and iree-runtime whereas iree-turbine utilizes a version number in the format of X.Y.Z. Therefore, compatible versions cannot be derived from the version number. A common versioning scheme would be SemVer, but as the MAJOR version must be increased when incompatible API changes are introduced a cross-project version number (primarily a shared MAJOR version) cannot be guaranteed if APIs are not identical. Switching to a non-CalVer scheme requires a package rename as the first release segment would otherwise need to be set to a number larger than 20240928, e.g. 30000000, or to introduce an N! epoch segment which however is not a convenient solution, see Python version epochs are broken.

Detailed proposal

A shared version format is proposed for the packages

• iree-base-compiler (formally named iree-compiler)
• iree-base-runtime (formally named iree-runtime)
• iree-turbine

Major or minor releases are published every 6 weeks for all packages uniformly. Based on logistics and/or practical engineering issues, releases may be delayed or deferred as needed. Patch versions for individual packages can be published outside of that cycle as needed.

A release number is in the format of X.Y.Z (MAJOR.MAJOR.PATCH).

• X and Y are defined as shared version numbers between all packages.
• The patch level Z MAY be incremented individually.
• A PATCH release contains only bug fixes and the version Z (x.y.Z) MUST be incremented. A bug fix is an internal change that fixes incorrect behavior and MUST NOT introduce breaking changes.
• A MINOR release (unlike SemVer) as well as a MAJOR release MAY contain backwards-incompatible, breaking changes, like API changes and removals and furthermore bug fixes and new features.

Development and nightly releases:

• Development builds (e.g. from a regular CI) MUST be released with a version number defined as X.Y.Z.devN, where N is a build number.
• Nightly releases MUST be released with a version number defined as X.Y.ZrcYYYYMMDD.
• The intent is to promote a recent, high quality release candidate to a final version. Binary stamps and tools will continue to report the original release candidate version.

The following semantics apply:

• If the version X (X.y.z) is increased for one package, the version number change MUST be adopted by all (other) packages. The same applies for the version Y (x.Y.Z).
• If the version X or Y are changed, Z MUST be set 0.
• After a release, either Y or Z MUST be increased to ensure precedence of nightly builds.
  For example:
  • The latest stable release published on November 15th 2024 is versioned as version 3.0.0.
  • The next nightly builds are released as 3.0.1rc20241116 or 3.1.0rc20241116.
  • The next stable release is released as 3.0.1 or 3.1.0.

Additional version information

With switching from CalVer to the proposed versioning scheme, the build date is not encoded in the version number any longer. However, additional information is provided by --version, e.g. iree-compile --version gives:

IREE (https://iree.dev):
  IREE compiler version 20240730.970 @ d39c3c56682e006e842b32aa6f38c272f77c8f3c
  LLVM version 20.0.0git
  Optimized build

which can be extended by the build date.

Implementation plan

Each project will have a version_info.json file containing the latest X.Y.Z version. Local, pull request, and nightly builds will read from this file and append their own suffixes to it. When a new release is promoted to PyPI from a nightly release, a script will be used to edit the embedded version, removing any rcYYYYMMDD suffix and then we will upgrade the version in each version_info.json file so future builds will use new versions. The new releases will start at version 3.0.0, since iree-turbine is currently 2.4.1.

Timeline

We would like to begin implementation work soon and have this completed within ~2 weeks.

[ScottTodd]

Highlighting an important detail that could be missed: with these version changes, existing workflows that use

python -m pip install iree-compiler iree-runtime

will need to be replaced with new packages

python -m pip install iree-base-compiler iree-base-runtime

Simply switching the version scheme on the existing packages would require starting with a version greater than the existing calver (20240828), or using Python version epochs, which are broken.

After rolling out the initial releases for each package, we can also explore ergonomics improvements like functional or meta packages that themselves depend on both "base" packages, so users can install a single project or the individual packages if they want precise control.

We can also publish tombstone package releases to the iree-compiler and iree-runtime projects that warn about the name change and maybe eventually (after years?) remove the old names/packages entirely.

[ScottTodd]

One open question is where we'll publish nightly releases to.

We currently push a new release every night to https://github.com/iree-org/iree/releases and a release index to https://iree.dev/pip-release-links.html using this script: https://github.com/iree-org/iree/blob/main/build_tools/scripts/generate_release_index.py . We could switch to a single "dev-wheels" release like https://github.com/nod-ai/SHARK-Platform/releases/tag/dev-wheels with a release index generated for us by GitHub like https://github.com/nod-ai/SHARK-Platform/releases/expanded_assets/dev-wheels .

Even if we rename the packages to iree-base-runtime and iree-base-compiler, we should be able to continue using the current system. Maybe as a future refactoring we can switch to the single release style.

Eventually we could also push nightly / pre-release versions of packages to pypi so users can just pass --pre instead of -f, --find-links <url>.

[stellaraccident]

Whatever helps you get bootstrapped. These things usually require a cascade of changes. But it would be good to get off of the old way. It's long in the tooth and creates a ton of tag spam.

If building a new index scraper, we probably want it to scrape all of the dev wheel locations across the projects and make one consolidated index file.

[ScottTodd]

Oh, I just found / re-remembered that iree-turbine versioning is intended to be based on PyTorch versions. I presume we're departing from that now, but using the existing 2.* versions as a starting point for our new 3.* versions across all packages?

The versioning scheme for iree-turbine is rooted on the then-current PyTorch released version, with optional date-based dev/pre-release suffixes (i.e. rcYYYYMMDD or devYYYYMMDD) or intra PyTorch releases (i.e. postVVVV).

This process is being trialed to correspond with the 2.3.0 release of PyTorch. In this scenario, the pinned nightly build of IREE is considered current and promoted as part of the Turbine release to PyPI (and the release is marked as not pre-release on the GitHub releases page).

I just pushed iree-turbine version 2.5.0 (https://github.com/iree-org/iree-turbine/releases/tag/v2.5.0), which I guess we could say coincides with PyTorch 2.5.0 (https://github.com/pytorch/pytorch/releases/tag/v2.5.0), but that's mostly a coincidence.

We could also have iree-turbine keep tracking PyTorch versions and instead start the iree-base-compiler/iree-base-runtime versions at 1.0.0. I do like taking this opportunity to use a common version scheme across all of our packages, diverging from external projects like PyTorch.

[ScottTodd]

That quote is from https://github.com/iree-org/iree/blob/main/RELEASING.md , which also then has this section:

In the future, we would like to adopt a real versioning scheme (beyond the
nightly calver+build number scheme) and manage promotion and pinning of the
core IREE dep more explicitly and in alignment with how downstreams are using
it.

[ScottTodd]

We are starting to roll out the new versions and package names now. Hoping to have nightly releases of iree-base-compiler and iree-base-runtime tonight, then packages on PyPI tonight or tomorrow.

[ScottTodd]

This new version scheme has now been rolled out completely with https://github.com/iree-org/iree/releases/tag/iree-3.0.0 and documented at https://iree.dev/developers/general/versioning-scheme/.

Some follow-up tasks:

• Consolidate pip index pages across repositories #19193
• Mark the old iree-compiler and iree-runtime Python packages as deprecated somehow (push a new release of each using calver, log a warning on import?)