Clarify definition of "minor" vs "major" release

[jamestwebber]

Documentation

I noticed this in a discussion but it was off-topic there. Either I'm misreading things, but it seems like the definition of major and minor release is inconsistent in the documentation. See this page (bold mine):

Python’s C API is covered by the Backwards Compatibility Policy, PEP 387. While the C API will change with every minor release (e.g. from 3.9 to 3.10), most changes will be source-compatible, typically by only adding new API. Changing existing API or removing API is only done after a deprecation period or to fix serious issues.

CPython’s Application Binary Interface (ABI) is forward- and backwards-compatible across a minor release (if these are compiled the same way; see Platform Considerations below). So, code compiled for Python 3.10.0 will work on 3.10.8 and vice versa, but will need to be compiled separately for 3.9.x and 3.10.x.

Here, the 11 in 3.11 is referred to as a minor release: the API can change when that changes, but within such a release it should be stable.

In other parts of Python documentation, most notably python.org, 3.11 (or 3.10, etc) is referred to as a "major release".

The FAQ is less than clear on this (again bold mine):

How does the Python version numbering scheme work?¶
Python versions are numbered “A.B.C” or “A.B”:

• A is the major version number – it is only incremented for really major changes in the language.
• B is the minor version number – it is incremented for less earth-shattering changes.
• C is the micro version number – it is incremented for each bugfix release.

See PEP 6 for more information about bugfix releases.

Not all releases are bugfix releases. In the run-up to a new major release, a series of development releases are made, denoted as alpha, beta, or release candidate. Alphas are early releases in which interfaces aren’t yet finalized; it’s not unexpected to see an interface change between two alpha releases. Betas are more stable, preserving existing interfaces but possibly adding new modules, and release candidates are frozen, making no changes except as needed to fix critical bugs.

Most of the time this is not a big concern but particularly for statements about long-term compatibility (like the C API page above) I think this is rather confusing.

Linked PRs

• gh-105844: Consistently use 'minor version' for X.Y versions #105851
• [3.11] gh-105844: Consistently use 'minor version' for X.Y versions (GH-105851) #105852
• [3.12] gh-105844: Consistently use 'minor version' for X.Y versions (GH-105851) #105853
• gh-105844: Use devguide terminology to denote versions #105882
• [3.12] gh-105844: Use devguide terminology to denote versions (GH-105882) #105892
• [3.11] gh-105844: Use devguide terminology to denote versions (GH-105882) #105893

[erlend-aasland]

Most of the time this is not a big concern but particularly for statements about long-term compatibility (like the C API page above) I think this is rather confusing.

I don't follow; I cannot not find any version inconsistencies on https://docs.python.org/3/c-api/stable.html. As far as I can see, minor version is used consistently there.

The FAQ is slightly inconsistent, though. Perhaps PEP-602 also needs an update¹.

Footnotes

1. PEP issues must be reported to https://github.com/python/peps; python.org inconsistencies at https://github.com/python/pythondotorg) ↩

[erlend-aasland]

Resolved with:

• gh-105844: Consistently use 'minor version' for X.Y versions #105851
• [3.11] gh-105844: Consistently use 'minor version' for X.Y versions (GH-105851) #105852
• [3.12] gh-105844: Consistently use 'minor version' for X.Y versions (GH-105851) #105853

(Backports are approved, pending merge)

[jamestwebber]

I don't follow; I cannot not find any version inconsistencies on https://docs.python.org/3/c-api/stable.html. As far as I can see, minor version is used consistently there.

The FAQ is slightly inconsistent, though. Perhaps PEP-602 also needs an update.

Yeah I just meant it was confusing to me when looking across multiple places. In particular the announcement of new releases got me used to thinking of them as "major". Thanks for the updates!

[erlend-aasland]

See @CAM-Gerlach's review of python/peps#3174 (python/peps#3174 (review)). I see now that my docs update could be made even clearer, by using the established release naming convention used in the devguide. 3.11 and 3.12 are feature releases, not minor releases.