Our versioning scheme currently follows Graal releases, for example 25.0. We'd like to switch to using the Python version (i.e. 3.12) as the primary version and keep the Graal version as secondary.

The problem

Many tools are built to expect the python version for any implementation. This has resulted in several inconsistencies and hacks. For example setup-python github action would use graalpy-25.0 whereas setup-uv action would use graalpy-3.12. Another example is maturin that contains a hardcoded table that maps between the two versioning schemes. It is also more difficult for humans to know which python version to find in which release. Another example is tox that doesn't support versioning GraalPy at all.

The proposal

• Standalone release artifacts would be versioned with $pythonVersion.$graalVersion, for example 3.12.8.25.1.0 with artifact filename graalpy-3.12.8.25.1.0-linux-aarch64.tar.gz. The separator between the python version and graal version is still up to discussion.
• Maven artifacts would retain the Graal versioning scheme. Java users are more likely to care about the Graal version and there are no tools that expect the python version.
• There would be no observable change from within the interpreter, sys.version_info would still report the python version and sys.implementation.version would still report the Graal version. C macros GRAALPY_VERSION and GRAALPY_VERSION_NUM would also keep the Graal version. The ABI tag would stay the same.

Risks

• 3.12 compares as lesser to 25.0, so that tools sorting on the version would see the new version as older. However, in practice nearly all tools require to specify the python version explicitly.
• setup-python used to be quite unresponsive to our PRs, so we shouldn't assume that we can merge anything there within a reasonable timeframe

Potentially affected projects

The list of projects that we know that might need changes beyond normal version bump:

• setup-python - Currently uses Graal version, versiong parsing code is here. The regex there would work, but it might not correctly sort graalpy releases that only differ after the fourth digit group (minor graal version). Needs to be investigated
• cibuildwheel - Currently uses Graal version without a dot (i.e. gp242)
• uv - Already uses the python version, has a CI bot that maintains the version list. We would probably just need to update the bot
• maturin - Already uses the python version, has a hardcoded table for that. We would need to add a default rule to the table that passes the version through.
• tox - Currently supports just unversioned graalpy. We should contribute support for versions and maybe remove the unversioned graalpy or at least make sure it sorts correctly
• pyenv - Uses exact versions and the installation scripts are generated manually by us, so there should be no change needed except our own scripts
• pyenv-win - Has a CI bot for adding new versions, might need updating