-
-
Notifications
You must be signed in to change notification settings - Fork 1.6k
Release PEPs: Use 'feature release' instead of 'minor version' to avoid ambiguity #3174
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
See also python/cpython#105844 |
I agree that this is confusing. To what extent do we want to edit historical documents though? |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It seems there is still going to be inevitable ambiguity and confusion with using either "major" or "minor" to refer to Python 3.x feature releases, as it these words overloaded with two entirely distinct meanings: which segment that version is in the version number (i.e. a "minor" release), and whether or not the release contains new features and breaking changes, as one would expect with a "major" release. Depending on which the reader assumes, they could just as easily draw the wrong conclusion with either "minor" or "major".
Therefore, I suggest we avoid this problem entirely and refer to these by the standard, unambiguous term "feature releases", which is what I've generally seen elsewhere when referring to the overall release rather than in the specific context of the numerical version segment, e.g. on the Versions and Development cycle pages of the devguide (that formally define Python's versioning policy), e.g.:
feature fixes, bugfixes, and security fixes are accepted for the upcoming feature release.
There is a branch for each feature version, whether released or not (e.g. 3.7, 3.8).
The main branch is the branch for the next feature release
new minor versions are feature releases; they get released annually, from the current in-development branch;
At some point during the life-cycle of a release, a new maintenance branch is created to host all bug fixing activity for further micro versions in a feature version (3.8.1, 3.8.2, etc.).
A branch for a previous feature release, currently being maintained for bug fixes, or for the next feature release in its beta or release candidate stages.
...and many others. "Minor version" is referred to on those pages, but generally only in the explicit context of the version segment, e.g. the example above or e.g.
After the final release of a new minor version (3.x.0)...
or
For Python 3.1.2 final, that is a major version of 3, a minor version of 1, and a micro version of 2.
Likewise, 3.N.Z releases aren't called "minor releases"; "micro" is just used to refer to the version segment, while the releases themselves are called "bugfix releases" or "security releases":
releases produced from a maintenance branch are called bugfix or maintenance releases; the terms are used interchangeably. These releases have a micro version number greater than zero.
TL;DR: I suggest we follow the lead of the most relevant devguide page here and use "feature version" instead of "minor version", unless explicitly referring to the version number segment.
+1 for "feature release". Is this in the dev guide anywhere? |
See my previous comment 😉 |
Derp, I didn't click the links, just read the text of the email :D My bad! |
That totally makes sense, @CAM-Gerlach; thanks! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I had one minor (heh) suggestion. Other than that, grepping through the PEPs I did see a number of other instances of this, but all the ones I checked were either explicitly in the context of the version number (and often mentioned major as well), and thus "minor" was appropriate, or they were on old, non-active PEPs.
Thanks!
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
One could expect that when using SemVer, but Python does not use SemVer (and predates it). Anyway, +1 for "feature release" to help avoid the reader making such assumptions. |
Right, of course—but given its prevalence, and it's particular association with those specific terms (major/minor/micro), many readers are likely to think that (given that's not explicitly stated every time its used), which (as you say) "feature release" avoids. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM, thanks @erlend-aasland !
Thanks for the reviews! |
📚 Documentation preview 📚: https://pep-previews--3174.org.readthedocs.build/