Add calendar versioning (calver) support to django.utils.version helpers

[Natalia Bidart]

​DEP 20 moves Django to calendar versioning (calver), YYYY[.N], starting with the 2028 release. The helpers in django.utils.version assume the X.Y[.Z] scheme and produce wrong output for calendar version tuples:

• get_main_version((2028, 0, 0, "final", 0)) returns "2028.0" instead of "2028"
• get_docs_version((2028, 5, 0, "final", 0)) returns "2028.5" instead of "2028"

[Natalia Bidart]

Worth mentioning: under the new layout, django.VERSION[:2] is no longer constant across the patch releases of a given feature release (it is (2028, 0) for 2028, but (2028, 1) once the first patch release ships), so third-party checks of the form django.VERSION[:2] == (X, Y) or > (2028, 0) need to become whole-year thresholds such as >= (2029, 0).

[Natalia Bidart]

Related (counterpart) djangoproject.com PR: ​https://github.com/django/djangoproject.com/pull/2733

[Carlton Gibson]

Thanks for opening this Natalia. I'll have a play. (Do you have a WIP branch already?)

Two initial comments:

get_main_version((2028, 0, 0, "final", 0)) returns "2028.0" instead of "2028"
get_docs_version((2028, 5, 0, "final", 0)) returns "2028.5" instead of "2028"

The minor field shouldn't be used for the patch number. Indeed, we should probably drop it, aiming for, e.g., (2028, 0, "final", 0) — i.e. just using year and patch. The DEP discussed having the third number, and the possibility of re-adding it at a year change if there's some reason in the future, but we don't use it: it would always be 0, so it's redundant. Even if we were to keep it, we still shouldn't mis-use it. The monthly releases bump patch.

Worth mentioning: under the new layout, django.VERSION[:2]...

Yes, perfect example of where the old scheme's SemVer-look-a-like bites. The major+minor is the (in fact) major version™ that people are looking for. The new system will allow folks to pop just the first number to get the major version. (But we need to handle the transition.)

[Carlton Gibson]

Of course, if we're going to touch this logic, we could just use packaging. 🤔

With pip install packaging:

>>> from packaging.version import Version
>>> def v(string):
...     version = Version(string)
...     print(version.release)
...     print(version.public, version.is_prerelease, version.pre)
...
>>> v("2028")
(2028,)
2028 False None
>>> v("2028a1")
(2028,)
2028a1 True ('a', 1)
>>> v("2028.7")
(2028, 7)
2028.7 False None
>>>

Etc