Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 181ffb6

Browse files
hugovkerlend-aasland
hugovk
and
erlend-aasland
authored
PEP 2026: Update following discussion (#3860)
Co-authored-by: Erlend E. Aasland <[email protected]>
1 parent 92cf372 commit 181ffb6

File tree

1 file changed

+217
-53
lines changed

1 file changed

+217
-53
lines changed

‎peps/pep-2026.rst

Lines changed: 217 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,18 @@ Abstract
1414

1515
This PEP proposes updating the versioning scheme for Python to include
1616
the calendar year.
17-
This aims to make the support lifecycle clear
18-
by making it easy to see when a version was first released,
19-
and easier to work out when it will reach end of life (EOL).
17+
18+
Calendar Versioning (CalVer) makes *everything* easier to translate into
19+
calendar time rather than counting versions and looking up when they will be
20+
(or were) released:
21+
22+
* The support lifecycle is clear,
23+
making it easy to see when a version was first released.
24+
* Deprecations are easier to manage for maintainers and users.
25+
* It's easier to work out when a version will reach end of life (EOL).
26+
* It helps people, especially new learners, understand how old their installation is.
27+
* It's easier to reason about which versions of Python to support
28+
for libraries and applications.
2029

2130
Starting with what would have been Python 3.15,
2231
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:
201210
For example, 3.26 will be released in 2026.
202211
It makes it obvious when a release first came out.
203212

213+
Clarity of deprecation removal
214+
------------------------------
215+
216+
Warnings for deprecations often mention the version they will be removed in.
217+
For example:
218+
219+
DeprecationWarning: 'ctypes.SetPointerType' is deprecated and slated for
220+
removal in Python 3.15
221+
222+
However, once aware of CalVer, it is immediately obvious from the warning how
223+
long you have to to take action:
224+
225+
DeprecationWarning: 'ctypes.SetPointerType' is deprecated and slated for
226+
removal in Python 3.26
227+
204228
Clarity of support lifecycle
205229
----------------------------
206230

@@ -219,6 +243,45 @@ it’s much easier:
219243

220244
"26 + 5 = [20]31"
221245

246+
Clarity of installation age
247+
---------------------------
248+
249+
With the year in the version, it’s easier to work out how old your installation
250+
is. For example, with the current scheme, if you're using Python 3.15 in 2035,
251+
it's not immediately clear that it was first released in 2026 (and has been EOL
252+
since 2031).
253+
254+
With knowledge of CalVer, if you're using Python 3.26 in 2035, it's clear it was
255+
first released nine years ago and it's probably time to upgrade.
256+
257+
This can help prompt people to switch to supported releases still under security
258+
support, and help in teaching new users who may have older installations.
259+
260+
Clarity of version support
261+
--------------------------
262+
263+
CalVer makes it easier to reason about which versions of Python to support.
264+
265+
For example, without CalVer, setting your minimum compatible Python version to
266+
3.19 in 2031 sets an aggressive assumption regarding version adoption and
267+
support.
268+
269+
However, with CalVer, this is more obvious if setting the minimum to 3.30 in
270+
2031. For wider support, perhaps you prefer setting it to 3.26.
271+
272+
Similarly, library maintainers supporting all CPython upstream versions
273+
need to test against five versions (or six including the pre-release).
274+
275+
For example, in 2030, the supported versions without CalVer would be:
276+
277+
* 3.15, 3.16, 3.17, 3.18, 3.19
278+
279+
With CalVer they would be:
280+
281+
* 3.26, 3.27, 3.28, 3.29, 3.30
282+
283+
A maintainer can see at a glance which versions are current and need testing.
284+
222285
Non-goals
223286
---------
224287

@@ -280,56 +343,6 @@ Python 3.14 will be the last version before this change, released in 2025.
280343
Python 3.26 will be the first version after this change, released in 2026.
281344
There will be no Python 3.15 to 3.25 inclusive.
282345

283-
Backwards compatibility
284-
=======================
285-
286-
This version change is the safest of the CalVer options considered
287-
(see `rejected ideas <PEP 2026 rejected_>`_): we keep 3 as the major version,
288-
and the minor version is still two digits.
289-
The minor will eventually change to three digits but this is predictable,
290-
a long way off and can be planned for.
291-
292-
We retain the ``python3`` executable.
293-
294-
Version mapping
295-
---------------
296-
297-
Versions 3.15 to 3.25 inclusive will be skipped.
298-
Features, deprecations and removals planned for these will be remapped to the
299-
new version numbers.
300-
301-
For example, a deprecation initially planned for removal in 3.16 will instead
302-
be removed in 3.27.
303-
304-
+-------------+------------------+-----------------+
305-
| Old version | New version | Initial release |
306-
+=============+==================+=================+
307-
| 3.14 | 3.14 (no change) | 2025 |
308-
+-------------+------------------+-----------------+
309-
| 3.15 | 3.26 | 2026 |
310-
+-------------+------------------+-----------------+
311-
| 3.16 | 3.27 | 2027 |
312-
+-------------+------------------+-----------------+
313-
| 3.17 | 3.28 | 2028 |
314-
+-------------+------------------+-----------------+
315-
| 3.18 | 3.29 | 2029 |
316-
+-------------+------------------+-----------------+
317-
| 3.19 | 3.30 | 2030 |
318-
+-------------+------------------+-----------------+
319-
| 3.20 | 3.31 | 2031 |
320-
+-------------+------------------+-----------------+
321-
| 3.21 | 3.32 | 2032 |
322-
+-------------+------------------+-----------------+
323-
| 3.22 | 3.33 | 2033 |
324-
+-------------+------------------+-----------------+
325-
| 3.23 | 3.34 | 2034 |
326-
+-------------+------------------+-----------------+
327-
| 3.24 | 3.35 | 2035 |
328-
+-------------+------------------+-----------------+
329-
| 3.25 | 3.36 | 2036 |
330-
+-------------+------------------+-----------------+
331-
332-
333346
Security implications
334347
=====================
335348

@@ -359,6 +372,8 @@ errors out and tells the user to use ``python3.26`` instead.
359372
Rejected ideas
360373
==============
361374

375+
.. _PEP 2026 YY.0:
376+
362377
YY.0
363378
----
364379

@@ -381,6 +396,8 @@ Will we stick with `version 3 forever
381396
Another option would be to put the year in the major version and jump to 26.0.
382397
This could mean we could leapfrog all that 4.0 baggage.
383398

399+
.. _PEP 2026 Platform compatibility tags:
400+
384401
Platform compatibility tags
385402
'''''''''''''''''''''''''''
386403

@@ -466,6 +483,8 @@ it's still a 3 followed by two digits.
466483
`Flake8's flake8-2020 plugin <https://pypi.org/project/flake8-2020/>`__
467484
to help find the problems like these.
468485

486+
.. _PEP 2026 python3 command:
487+
469488
``python3`` command
470489
'''''''''''''''''''
471490

@@ -547,6 +566,151 @@ Change during 3.14 cycle
547566

548567
The Python 3.14 release must go ahead because: π.
549568

569+
Backwards compatibility
570+
=======================
571+
572+
This version change is the safest of the CalVer options considered
573+
(see `rejected ideas <PEP 2026 rejected_>`_): we keep 3 as the major version,
574+
and the minor version is still two digits.
575+
The minor will eventually change to three digits but this is predictable,
576+
a long way off and can be planned for.
577+
578+
We retain the ``python3`` executable.
579+
580+
Version mapping
581+
---------------
582+
583+
Versions 3.15 to 3.25 inclusive will be skipped.
584+
Features, deprecations and removals planned for these will be remapped to the
585+
new version numbers.
586+
587+
For example, a deprecation initially planned for removal in 3.16 will instead
588+
be removed in 3.27.
589+
590+
+-------------+------------------+-----------------+
591+
| Old version | New version | Initial release |
592+
+=============+==================+=================+
593+
| 3.14 | 3.14 (no change) | 2025 |
594+
+-------------+------------------+-----------------+
595+
| 3.15 | 3.26 | 2026 |
596+
+-------------+------------------+-----------------+
597+
| 3.16 | 3.27 | 2027 |
598+
+-------------+------------------+-----------------+
599+
| 3.17 | 3.28 | 2028 |
600+
+-------------+------------------+-----------------+
601+
| 3.18 | 3.29 | 2029 |
602+
+-------------+------------------+-----------------+
603+
| 3.19 | 3.30 | 2030 |
604+
+-------------+------------------+-----------------+
605+
| 3.20 | 3.31 | 2031 |
606+
+-------------+------------------+-----------------+
607+
| 3.21 | 3.32 | 2032 |
608+
+-------------+------------------+-----------------+
609+
| 3.22 | 3.33 | 2033 |
610+
+-------------+------------------+-----------------+
611+
| 3.23 | 3.34 | 2034 |
612+
+-------------+------------------+-----------------+
613+
| 3.24 | 3.35 | 2035 |
614+
+-------------+------------------+-----------------+
615+
| 3.25 | 3.36 | 2036 |
616+
+-------------+------------------+-----------------+
617+
618+
Forwards compatibility
619+
======================
620+
621+
Future change in cadence
622+
------------------------
623+
624+
This PEP proposes no change to the annual release cadence as defined in
625+
:pep:`602`, which lays out
626+
:pep:`many good reasons for annual releases <602#rationale-and-goals>`
627+
(for example, smaller releases with a predictable release calendar,
628+
and syncing with external redistributors).
629+
However unlikely, should we decide to change the cadence in the future, CalVer
630+
does not preclude doing so.
631+
632+
Less frequent
633+
'''''''''''''
634+
635+
If we went to *fewer than one release per year*, the proposed CalVer scheme
636+
still works; indeed, it even helps people know in which year to expect the
637+
release. For example, if we released every second year starting in 2036:
638+
639+
* 3.36.0 would be released in 2036
640+
* 3.38.0 would be released in 2038
641+
* and so on
642+
643+
Ecosystem changes depend in part on how the the hypothetical cadence-changing
644+
PEP updates :pep:`387` (Backwards Compatibility Policy). If, for example, it
645+
requires that the deprecation period must be at least one feature release and
646+
not the current two (to maintain the minimum two years), CalVer has the benefit
647+
over the status quo in requiring no changes to planned removal versions
648+
(other than adjusting any falling in non-release years).
649+
650+
.. _PEP 2026 More frequent:
651+
652+
More frequent
653+
'''''''''''''
654+
655+
If we went to *more than one release per year*, here are some options.
656+
For example, if we released in April and October starting in 2036, the next
657+
four releases could be:
658+
659+
+---------------+--------------------------------+-----------+-----------+-----------+-----------+
660+
| Scheme | Notes | 2036 a | 2036 b | 2037 a | 2037 b |
661+
+===============+================================+===========+===========+===========+===========+
662+
| YY.MM.micro | Year as major, month as minor | 36.04.0 | 36.10.0 | 37.04.0 | 37.10.0 |
663+
+---------------+--------------------------------+-----------+-----------+-----------+-----------+
664+
| YY.x.micro | Year as major, | 36.1.0 | 36.2.0 | 37.1.0 | 37.2.0 |
665+
| | serial number as minor | | | | |
666+
+---------------+--------------------------------+-----------+-----------+-----------+-----------+
667+
| 3.YYMM.micro | Combine year and month | 3.3604.0 | 3.3610.0 | 3.3704.0 | 3.3710.0 |
668+
| | as minor | | | | |
669+
+---------------+--------------------------------+-----------+-----------+-----------+-----------+
670+
| 3.YYx.micro | Combine year and serial number | 3.360.0 | 3.361.0 | 3.370.0 | 3.371.0 |
671+
| | as minor | | | | |
672+
+---------------+--------------------------------+-----------+-----------+-----------+-----------+
673+
| 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 |
674+
+---------------+--------------------------------+-----------+-----------+-----------+-----------+
675+
| 3.major.micro | No more CalVer: | 3.36.0 | 3.37.0 | 3.38.0 | 3.39.0 |
676+
| | increment minor +-----------+-----------+-----------+-----------+
677+
| | | 3.50.0 | 3.51.0 | 3.52.0 | 3.53.0 |
678+
| | +-----------+-----------+-----------+-----------+
679+
| | | 3.100.0 | 3.101.0 | 3.102.0 | 3.103.0 |
680+
+---------------+--------------------------------+-----------+-----------+-----------+-----------+
681+
| 4.major.micro | No more CalVer: | 4.0.0 | 4.1.0 | 4.2.0 | 4.3.0 |
682+
+---------------+ increment major +-----------+-----------+-----------+-----------+
683+
| 5.major.micro | | 5.0.0 | 5.1.0 | 5.2.0 | 5.3.0 |
684+
+---------------+--------------------------------+-----------+-----------+-----------+-----------+
685+
686+
The YY options would require addressing issues around the
687+
`platform compatibility tags <PEP 2026 platform compatibility tags_>`__,
688+
the `python3 command <PEP 2026 python3 command_>`_, and code
689+
`assuming the version always begins with 3 <PEP 2026 Ecosystem changes_>`__.
690+
691+
The options keeping major version 3 but changing the minor to three or four
692+
digits would also need to address code
693+
`assuming the version is always two digits <PEP 2026 Ecosystem changes_>`__.
694+
695+
The option adding an extra month segment is the biggest change as code would
696+
need to deal with a four-part version instead of three.
697+
698+
The options dropping CalVer would be the most conservative
699+
allowing the major and minor to be chosen freely.
700+
701+
No more CalVer
702+
--------------
703+
704+
Adopting CalVer now does not preclude moving away CalVer in the future,
705+
for example, back to the original scheme, to SemVer or another scheme.
706+
Some options are `listed in the table above <PEP 2026 More frequent_>`__.
707+
If wanting to make it clear the minor is no longer the year,
708+
it can be bumped to a higher round number (for example, 3.50 or 3.100)
709+
or the major version can be bumped (for example, to 4.0 or 5.0).
710+
Additionally, a `version epoch
711+
<https://packaging.python.org/en/latest/specifications/version-specifiers/#version-epochs>`__
712+
could be considered.
713+
550714
Footnotes
551715
=========
552716

0 commit comments

Comments
 (0)