[Python-Dev] Python version numbers (original) (raw)

Paul G paul at ganssle.io
Tue Apr 3 13:09:13 EDT 2018

On 04/03/2018 12:36 PM, Brett Cannon wrote:

On Tue, 3 Apr 2018 at 07:39 Paul G <paul at ganssle.io> wrote:

Paul's point is that he knows e.g. code working in 3.6.0 will work when he upgrades to 3.6.5, and if his code is warning-free and works with all future statements in 3.6 that it will work fine in 3.7. With CalVer you could make a similar promise if you keep the major version the year of release and then keep our feature/bugfix number promise like we already have, but at that point who cares about the year?

I think it is reasonable to use a scheme like this:

YY.MM.patch

The canonical release is numbered by Year-Month, and patches intended to add new features and break nothing get a patch release, no matter when they are released. That allows for simple pinning.

While we have an 18 month schedule for releases, we also can't guarantee we will hit our release window in a specific year, e.g. 3.6 was first released in December but we could have slipped into January. That makes promises for a specific version tied to a year number problematic.

I think no promises for a specific version number need to be made until after a release is made. Using calendar-based versioning facilitates using a calendar-based deprecation schedule, irrespective of how many releases have occurred between the deprecation and the removal. If the promise is "we will support this feature for 5 years", then you know ahead of time the minimum version number in which that feature will be removed.

So say you have a function foo() called in your library that is deprecated in the 20.05.0 feature release. You know at that point that any release after 25.05.0 will drop support for foo, so on your next release that uses foo(), you set the upper bound on your requires_python to <25.05.0. It doesn't matter if that release happens in 2025-08 or 2027-01.

Similarly if you are developing some cutting edge library that is using features from the "feature release" branch, you can set requires_python to some value with a month greater than the current calendar version.

If we chose to switch to semantic versioning, we would probably make it so that any version that makes a future statement the new default is a major version bump. But then the issue becomes the stdlib. Do we drop everything that was previously deprecated in the stdlib for every major version bump? That might be a bit drastic when e.g. all you did was make old code that used await as a variable name raise a SyntaxError. And saying "deprecated for two versions" then becomes messy because you have no idea what that second version will be. And what if you really want to get rid of something in the next release? Can a single module dropping a function force a version bump for Python itself?

This is why I suggested a calendar-version based approach, along with a pre-commitment that the "rolling backwards compatibility window" would be a specific amount of time, not a specific number of versions. It makes it very easy to make predicitions about when specific features are falling in and out of that window, because each deprecation warning can come pre-populated with the length of the deprecation period and, as a result, the maximum version that will support that feature. If that were done, you could even concievably write a "compatibility checker" tool that can be run against a repo to calculate the requires_python upper bound and to order deprecation warnings by urgency.

I have not read the other thread, but knowing it's from Lukasz makes me guess he wants to move up the minor number to become the major one in terms of our current semantics so we have a rolling window of support. That would mean that as long as you are warnings-free and run fine with all future statements turned on for version N then N+1 should work for you without modification (sans relying on buggy semantics). That approach would deal with the above issues cleanly while dropping what our current major number semantics which some people view as a fallacy and are getting upset over (I'm personally +0 on this last idea as it's easy to explain to folks and I have been doing Python version explanations a lot over the last several months).

Lukasz did not propose any changes to the version number semantics, just the deprecation schedule. I was suggesting that if this happens, it's probably a good idea to "drop" the major version number - either by incrementing it with each release that breaks backwards compat (which, for a sufficiently continuous influx of rolling deprecations should be basically every feature release), or by switching to a calendar-based system. From above, I think a calendar-based system has the best features for end users.

More information about the Python-Dev mailing list