GeezerVison is showing github.com — Clarify definition of "minor" vs "major" release · Issue #105844 · python/cpython
Clarify definition of "minor" vs "major" release #105844DescriptionDocumentation
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
Activityerlend-aasland commented on Jun 16, 2023
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 update1.
erlend-aasland commented on Jun 16, 2023 Resolved with:
(Backports are approved, pending merge) jamestwebber commented on Jun 16, 2023 ContributorAuthor More actions
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 commented on Jun 17, 2023 Reacted by James Webber and C.A.M. Gerlach changed the title [-]definition of "minor" vs "major" release[/-] [+]Clarify definition of "minor" vs "major" release[/+] on Jun 18, 2023
MetadataMetadataDevelopmentNo branches or pull requestsIssue actions
|