python · hugovk · Jul 11, 2024 · Jun 19, 2024 · Jul 10, 2024 · Jul 11, 2024
@@ -14,9 +14,18 @@ Abstract
 
 This PEP proposes updating the versioning scheme for Python to include
 the calendar year.
-This aims to make the support lifecycle clear
-by making it easy to see when a version was first released,
-and easier to work out when it will reach end of life (EOL).
+
+Calendar Versioning (CalVer) makes *everything* easier to translate into
+calendar time rather than counting versions and looking up when they will be
+(or were) released:
+
+* The support lifecycle is clear,
+  making it easy to see when a version was first released.
+* Deprecations are easier to manage for maintainers and users.
+* It's easier to work out when a version will reach end of life (EOL).
+* It helps people, especially new learners, understand how old their installation is.
+* It's easier to reason about which versions of Python to support
+  for libraries and applications.
 
 Starting with what would have been Python 3.15,
 the version is 3.YY.micro where YY is the year of initial release:
@@ -201,6 +210,21 @@ and encode the year in the minor version:
 For example, 3.26 will be released in 2026.
 It makes it obvious when a release first came out.
 
+Clarity of deprecation removal
+------------------------------
+
+Warnings for deprecations often mention the version they will be removed in.
+For example:
+
+   DeprecationWarning: 'ctypes.SetPointerType' is deprecated and slated for
+   removal in Python 3.15
+
+However, once aware of CalVer, it is immediately obvious from the warning how
+long you have to to take action:
+
+   DeprecationWarning: 'ctypes.SetPointerType' is deprecated and slated for
+   removal in Python 3.26
+
 Clarity of support lifecycle
 ----------------------------
 
@@ -219,6 +243,45 @@ it’s much easier:
 
     "26 + 5 = [20]31"
 
+Clarity of installation age
+---------------------------
+
+With the year in the version, it’s easier to work out how old your installation
+is. For example, with the current scheme, if you're using Python 3.15 in 2035,
+it's not immediately clear that it was first released in 2026 (and has been EOL
+since 2031).
+
+With knowledge of CalVer, if you're using Python 3.26 in 2035, it's clear it was
+first released nine years ago and it's probably time to upgrade.
+
+This can help prompt people to switch to supported releases still under security
+support, and help in teaching new users who may have older installations.
+
+Clarity of version support
+--------------------------
+
+CalVer makes it easier to reason about which versions of Python to support.
+
+For example, without CalVer, setting your minimum compatible Python version to
+3.19 in 2031 sets an aggressive assumption regarding version adoption and
+support.
+
+However, with CalVer, this is more obvious if setting the minimum to 3.30 in
+2031. For wider support, perhaps you prefer setting it to 3.26.
+
+Similarly, library maintainers supporting all CPython upstream versions
+need to test against five versions (or six including the pre-release).
+
+For example, in 2030, the supported versions without CalVer would be:
+
+* 3.15, 3.16, 3.17, 3.18, 3.19
+
+With CalVer they would be:
+
+* 3.26, 3.27, 3.28, 3.29, 3.30
+
+A maintainer can see at a glance which versions are current and need testing.
+
 Non-goals
 ---------
 
@@ -280,56 +343,6 @@ Python 3.14 will be the last version before this change, released in 2025.
 Python 3.26 will be the first version after this change, released in 2026.
 There will be no Python 3.15 to 3.25 inclusive.
 
-Backwards compatibility
-=======================
-
-This version change is the safest of the CalVer options considered
-(see `rejected ideas <PEP 2026 rejected_>`_): 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.
-
-We retain the ``python3`` executable.
-
-Version mapping
----------------
-
-Versions 3.15 to 3.25 inclusive will be skipped.
-Features, deprecations and removals planned for these will be remapped to the
-new version numbers.
-
-For example, a deprecation initially planned for removal in 3.16 will instead
-be removed in 3.27.
-
-+-------------+------------------+-----------------+
-| Old version | New version      | Initial release |
-+=============+==================+=================+
-| 3.14        | 3.14 (no change) | 2025            |
-+-------------+------------------+-----------------+
-| 3.15        | 3.26             | 2026            |
-+-------------+------------------+-----------------+
-| 3.16        | 3.27             | 2027            |
-+-------------+------------------+-----------------+
-| 3.17        | 3.28             | 2028            |
-+-------------+------------------+-----------------+
-| 3.18        | 3.29             | 2029            |
-+-------------+------------------+-----------------+
-| 3.19        | 3.30             | 2030            |
-+-------------+------------------+-----------------+
-| 3.20        | 3.31             | 2031            |
-+-------------+------------------+-----------------+
-| 3.21        | 3.32             | 2032            |
-+-------------+------------------+-----------------+
-| 3.22        | 3.33             | 2033            |
-+-------------+------------------+-----------------+
-| 3.23        | 3.34             | 2034            |
-+-------------+------------------+-----------------+
-| 3.24        | 3.35             | 2035            |
-+-------------+------------------+-----------------+
-| 3.25        | 3.36             | 2036            |
-+-------------+------------------+-----------------+
-
-
 Security implications
 =====================
 
@@ -359,6 +372,8 @@ errors out and tells the user to use ``python3.26`` instead.
 Rejected ideas
 ==============
 
+.. _PEP 2026 YY.0:
+
 YY.0
 ----
 
@@ -381,6 +396,8 @@ Will we stick with `version 3 forever
 Another option would be to put the year in the major version and jump to 26.0.
 This could mean we could leapfrog all that 4.0 baggage.
 
+.. _PEP 2026 Platform compatibility tags:
+
 Platform compatibility tags
 '''''''''''''''''''''''''''
 
@@ -466,6 +483,8 @@ it's still a 3 followed by two digits.
    `Flake8's flake8-2020 plugin <https://pypi.org/project/flake8-2020/>`__
    to help find the problems like these.
 
+.. _PEP 2026 python3 command:
+
 ``python3`` command
 '''''''''''''''''''
 
@@ -547,6 +566,151 @@ Change during 3.14 cycle
 
 The Python 3.14 release must go ahead because: π.
 
+Backwards compatibility
+=======================
+
+This version change is the safest of the CalVer options considered
+(see `rejected ideas <PEP 2026 rejected_>`_): 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.
+
+We retain the ``python3`` executable.
+
+Version mapping
+---------------
+
+Versions 3.15 to 3.25 inclusive will be skipped.
+Features, deprecations and removals planned for these will be remapped to the
+new version numbers.
+
+For example, a deprecation initially planned for removal in 3.16 will instead
+be removed in 3.27.
+
++-------------+------------------+-----------------+
+| Old version | New version      | Initial release |
++=============+==================+=================+
+| 3.14        | 3.14 (no change) | 2025            |
++-------------+------------------+-----------------+
+| 3.15        | 3.26             | 2026            |
++-------------+------------------+-----------------+
+| 3.16        | 3.27             | 2027            |
++-------------+------------------+-----------------+
+| 3.17        | 3.28             | 2028            |
++-------------+------------------+-----------------+
+| 3.18        | 3.29             | 2029            |
++-------------+------------------+-----------------+
+| 3.19        | 3.30             | 2030            |
++-------------+------------------+-----------------+
+| 3.20        | 3.31             | 2031            |
++-------------+------------------+-----------------+
+| 3.21        | 3.32             | 2032            |
++-------------+------------------+-----------------+
+| 3.22        | 3.33             | 2033            |
++-------------+------------------+-----------------+
+| 3.23        | 3.34             | 2034            |
++-------------+------------------+-----------------+
+| 3.24        | 3.35             | 2035            |
++-------------+------------------+-----------------+
+| 3.25        | 3.36             | 2036            |
++-------------+------------------+-----------------+
+
+Forwards compatibility
+======================
+
+Future change in cadence
+------------------------
+
+This PEP proposes no change to the annual release cadence as defined in
+:pep:`602`, which lays out
+:pep:`many good reasons for annual releases <602#rationale-and-goals>`
+(for example, smaller releases with a predictable release calendar,
+and syncing with external redistributors).
+However unlikely, should we decide to change the cadence in the future, CalVer
+does not preclude doing so.
+
+Less frequent
+'''''''''''''
+
+If we went to *fewer than one release per year*, the proposed CalVer scheme
+still works; indeed, it even helps people know in which year to expect the
+release. For example, if we released every second year starting in 2036:
+
+* 3.36.0 would be released in 2036
+* 3.38.0 would be released in 2038
+* and so on
+
+Ecosystem changes depend in part on how the the hypothetical cadence-changing
+PEP updates :pep:`387` (Backwards Compatibility Policy). If, for example, it
+requires that the deprecation period must be at least one feature release and
+not the current two (to maintain the minimum two years), CalVer has the benefit
+over the status quo in requiring no changes to planned removal versions
+(other than adjusting any falling in non-release years).
+
+.. _PEP 2026 More frequent:
+
+More frequent
+'''''''''''''
+
+If we went to *more than one release per year*, here are some options.
+For example, if we released in April and October starting in 2036, the next
+four releases could be:
+
++---------------+--------------------------------+-----------+-----------+-----------+-----------+
+| Scheme        | Notes                          | 2036 a    | 2036 b    | 2037 a    | 2037 b    |
++===============+================================+===========+===========+===========+===========+
+| YY.MM.micro   | Year as major, month as minor  | 36.04.0   | 36.10.0   | 37.04.0   | 37.10.0   |
++---------------+--------------------------------+-----------+-----------+-----------+-----------+
+| YY.x.micro    | Year as major,                 | 36.1.0    | 36.2.0    | 37.1.0    | 37.2.0    |
+|               | serial number as minor         |           |           |           |           |
++---------------+--------------------------------+-----------+-----------+-----------+-----------+
+| 3.YYMM.micro  | Combine year and month         | 3.3604.0  | 3.3610.0  | 3.3704.0  | 3.3710.0  |
+|               | as minor                       |           |           |           |           |
++---------------+--------------------------------+-----------+-----------+-----------+-----------+
+| 3.YYx.micro   | Combine year and serial number | 3.360.0   | 3.361.0   | 3.370.0   | 3.371.0   |
+|               | as minor                       |           |           |           |           |
++---------------+--------------------------------+-----------+-----------+-----------+-----------+
+| 3.YY.MM.micro | Add an extra month segment     | 3.36.04.0 | 3.36.10.0 | 3.37.04.0 | 3.37.10.0 |
++---------------+--------------------------------+-----------+-----------+-----------+-----------+
+| 3.major.micro | No more CalVer:                | 3.36.0    | 3.37.0    | 3.38.0    | 3.39.0    |
+|               | increment minor                +-----------+-----------+-----------+-----------+
+|               |                                | 3.50.0    | 3.51.0    | 3.52.0    | 3.53.0    |
+|               |                                +-----------+-----------+-----------+-----------+
+|               |                                | 3.100.0   | 3.101.0   | 3.102.0   | 3.103.0   |
++---------------+--------------------------------+-----------+-----------+-----------+-----------+
+| 4.major.micro | No more CalVer:                | 4.0.0     | 4.1.0     | 4.2.0     | 4.3.0     |
++---------------+ increment major                +-----------+-----------+-----------+-----------+
+| 5.major.micro |                                | 5.0.0     | 5.1.0     | 5.2.0     | 5.3.0     |
++---------------+--------------------------------+-----------+-----------+-----------+-----------+
+
+The YY options would require addressing issues around the
+`platform compatibility tags <PEP 2026 platform compatibility tags_>`__,
+the `python3 command <PEP 2026 python3 command_>`_, and code
+`assuming the version always begins with 3 <PEP 2026 Ecosystem changes_>`__.
+
+The options keeping major version 3 but changing the minor to three or four
+digits would also need to address code
+`assuming the version is always two digits <PEP 2026 Ecosystem changes_>`__.
+
+The option adding an extra month segment is the biggest change as code would
+need to deal with a four-part version instead of three.
+
+The options dropping CalVer would be the most conservative
+allowing the major and minor to be chosen freely.
+
+No more CalVer
+--------------
+
+Adopting CalVer now does not preclude moving away CalVer in the future,
+for example, back to the original scheme, to SemVer or another scheme.
+Some options are `listed in the table above <PEP 2026 More frequent_>`__.
+If wanting to make it clear the minor is no longer the year,
+it can be bumped to a higher round number (for example, 3.50 or 3.100)
+or the major version can be bumped (for example, to 4.0 or 5.0).
+Additionally, a `version epoch
+<https://packaging.python.org/en/latest/specifications/version-specifiers/#version-epochs>`__
+could be considered.
+
 Footnotes
 =========