PEP 2026: Calendar versioning for Python

[hugovk (Hugo van Kemenade)]

@rtpg

Going to throw out there that while YY.00 and YY.MM were explored, 3.YY.MM was not explored (so I guess 3.YY.MM.0, 3.YY.MM.1…).

I touched upon it but could more explicitly reject a four-(or more)-part version in the PEP. The proposal is to retain the familiar three-part 3.x.y shape for backwards compatibility:

@PEP 2026

This version change is the safest of the CalVer options considered (see rejected ideas): we keep 3 as the major version, and the minor version is still two digits. The minor will eventually change to three digits but this is predictable, a long way off and can be planned for.

And to minimise ecosystem changes:

@PEP 2026

[…] any novel change to the version inevitably does [break code] because people make assumptions, such as the major always being 3, or that the version parts are always single digits. […]

Therefore the 3.YY scheme is the safest and requires fewest changes, because the shape of the version doesn’t change: it’s still a 3 followed by two digits.

@rtpg

I wanted to mention 3.YY.MM mainly because it captures “3 is the brand” and “capture years and months” like Ubuntu or Black.

Addressed under non-goals: I propose 3.YY.micro where YY is the year of initial release, and micro is incremented for bugfix/security releases.

For example, 3.26.0 is the initial release in October 2026, 3.26.2 is the second bugfix release in February 2027. We retain the 3.YY for each feature release based on initial release; remember we support five feature releases at a time.

This is similar to Ubuntu’s micro: 22.04.0 was the initial release in 2022, 22.04.2 was a bugfix release in 2023.

@rtpg

“There’s nothing to gain from the 3” feels like a real point, but if you think about it nothing about version numbers in calver matters anyways! Why not 3.YYMM? Why not YYMM01, YYMM02, etc? The dots location in the string is information-less, yet we put it in because aesthetically it’s nice!

Sure, but we’re not designing from scratch. Why not those? To avoid breaking code that expects a three-part, two-dot version starting with 3 and followed by two parts of 1-2 digits; and:

@PEP 2026

However, [3.YYYY] is rejected as changing from two to four digits would break more code than 3.YY versioning.

---

@srittau

I don’t think that the proposed versioning format would help with the confusion. “3.26.5” very much looks like a SemVer version, the fact that uses some kind of CalVer is quite obscure.

However we’d be able to point to a clear statement saying “the major is always 3, minor is the year”, which I feel is much better than the ambiguous and confusing “major is bumped for really major changes in the language, minor for less earth-shattering changes”.

---

@pf_moore

While we’ve had people get confused because they assume SemVer, I don’t think anyone has had any particular issue once it’s been explained.

But when will we bump the major version? There is confusion around this. What exceptional, earth-shattering changes warrant a bump to 4? It comes up from time to time, but there’s little appetite for it and we don’t want to repeat 2-to-3. From the summit discussion:

“Python 3 is a brand at this point, and we should stick to it” said Guido van Rossum after sharing concerns that changes to the major version would break the ecosystem more than changes to the minor version. Others voiced concerns about changing the major version “3” including in the “python3” binary and for packaging such as “abi3” tag.

The proposal makes clear the major is always 3; there’ll be no Python 4.

@pf_moore

And we shouldn’t have to change our versioning just because some fans of SemVer think otherwise…

Indeed, but this isn’t the only reason. We bump the minor every year without fail. We’re unlikely to bump the major. I propose we do something useful with the minor.