rebuild versioning

[dhellmann]

If we are rebuilding the same source because of an issue in a build dependency, such as a compiler, how do we update the version of the wheel to indicate that it is new?

Related info:

• https://peps.python.org/pep-0440/
• https://peps.python.org/pep-0491/#file-name-convention
• https://packaging.python.org/en/latest/specifications/core-metadata/
• https://packaging.python.org/en/latest/specifications/binary-distribution-format/

[tiran]

The answer is post release, e.g. egg-1.2.3.post1 is the first respin of release egg-1.2.3.

Since upstream can release post releases to PyPI as well and we are technically rebuilds of the original build, I suggest the following: Our rebuilds bump the post release by n * 100 starting with n = 1 for the first rebuild. This gives upstream 99 post releases until it collides with our post releases.

• egg-1.2.3 has an implicit post number 0, so our first rebuild would be egg-1.2.3.post100.
• if we need to respin, then we release egg-1.2.3.post200
• if upstream releases egg-1.2.3.post1, then we rebuild as egg-1.2.3.post201.

[dhellmann]

@tiran , a while back @markmc pointed out "local versions" to me. That wasn't something I'd seen before. Have you seen it used?

[tiran]

Several project and build helpers use local identifiers. Setuptools-scm uses it to include VCS commit information in versions, egg-1.2.3.dev3+g012345678 is git (g) commit hash 012345678 and 3 commits (dev3) after tag 1.2.3. Torch uses it to mark CPU and ROCm builds, e.g. torch-2.2.2+cpu.cxx11.abi-cp312-cp312-linux_x86_64.whl (+cpu.cxx11.abi is the local version info for CPU-only build with C++ 11 ABI) or torch-2.2.2+rocm5.7-cp312-cp312-linux_x86_64.whl (AMD ROCm 5.7).

We should use local version to encode platform ABI, ISA extensions like AVX2, and GPU support. I'll write down my proposal next week and send it to the group.

[dhellmann]

Another thought on this: We have been trying to avoid tracking lots of manually managed metadata for each package. That means we won't necessarily have the equivalent of a spec file for any given wheel we're building. Where else can we track what the build history of something is, and how do we decide when to update the post version?