Release Pillow 3.0 after 2.9?

[hugovk]

One CPython core developer wrote last year:

My current expectation is that Python 4.0 will merely be "the release that comes after Python 3.9". That's it. No profound changes to the language, no major backwards compatibility breaks - going from Python 3.9 to 4.0 should be as uneventful as going from Python 3.3 to 3.4 (or from 2.6 to 2.7). I even expect the stable Application Binary Interface (as first defined in PEP 384) to be preserved across the boundary.

We could consider following the Python core versioning scheme. After 2.9 comes 3.0, not 2.10. Just another release. It fits well with the "release whatever is ready each quarter".

I know version numbers aren't a decimal number (that second dot in the full x.y.z is a giveaway), but it's that little bit clearer to avoid double digit version numbers. No need to wonder if 2.11 is later that 2.2, no bugs caused by dodgy coding (see why Windows 9 was skipped).

(Python 2.7 is a bit of a special case because it's hanging around for maintenance releases until at least 2020 and will soon hit 2.7.10 as can't really roll over to 2.8/2.9.)

Is the release after 2.9 big or important enough to be given a 3.0 version number? Well, 10 releases of Pillow is a great achievement in itself, especially with quarterly releases.

Having said that, if anything "big" comes along before 2.9, it might make sense to bump up to 3.0. For example Python 3 support warranted the bump to Pillow 2.0.

Thoughts?

[aclark4life]

I'm not sure about other features/changes/etc, but if renaming the Pillow distribution to pillow proves to be desirable, then I'd be comfortable doing it then.

And in general, I'm fine with "3.0 comes after 2.9" vs. 2.10.

[nicktimko]

How about also renaming modules/packages to lower-case versions a la Python 2's Queue, SimpleHTTPServer, StringIO...

[hugovk]

I'm not so keen on renaming just to follow conventions, as in this case it would break lots of existing code that uses Pillow, and to support multiple versions require lots of ugly code like this:

try: 
    import Xyz
except ImportError:
    import xyz

It's basically an API break that can be avoided.

[radarhere]

Some methods are marked as deprecated:: 2.0, for example https://github.com/python-pillow/Pillow/blob/master/PIL/Image.py#L1252

Is 3.0 a reasonable point in time to remove them completely?

[hugovk]

@radarhere Generally we've been putting deprecation warnings in for a release or two before dropping things entirely.

[radarhere]

@hugovk okay. so 3.0 is well past time for 2.0 deprecations to be removed then?

[hugovk]

@radarhere For me, yes. What do others think?

For new deprecating things, we've put warnings that output back to the user. But I suppose deprecation warnings like that one in the docstring/documentation are still valid, especially after 10 releases/2.5 years.

It may be worth listing in release notes the removed deprecations, and what should be used instead (e.g. "New code should use PIL.ImageChops.offset").

[aclark4life]

+1 for aggressive but fair deprecation, meaning: do remove deprecated feature in X.X.X after deprecating feature in X.X.X - 0.1.0. So, starting with 3.0.0 we can do this:

• Clear slate of past overdue deprecation removals
• Mark newly deprecated feature(s) as deprecated in 3.0.0.
• Remove features marked deprecated in 3.0.0 no sooner than 3.1.0.
• Add new deprecations warnings no sooner than next "major" release e.g. 3.1.0, 3.2.0, etc.
• No deprecation warnings to be added in point AKA "bug fix" releases e.g. 3.0.1.
• Document deprecation and replacement feature no later than time of removal but preferably at time of deprecation mark.

[nicktimko]

Could Ctrl-C, Ctrl-V from another project:

A major release may deprecate certain features from previous releases. If a feature is deprecated in version A.B, it will continue to work in versions A.B and A.B+1 but raise warnings. It will be removed in version A.B+2.

So, for example, if we decided to start the deprecation of a function in Django 1.7 PIL 3.0:

• Django 1.7 PIL 3.0 will contain a backwards-compatible replica of the function which will raise a RemovedInDjango19Warning RemovedInPIL32. This warning is silent by default; you can turn on display of these warnings with the -Wd option of Python.
• Django 1.8 PIL 3.1 will still contain the backwards-compatible replica. This warning becomes loud by default, and will likely be quite annoying.
• Django 1.9 PIL 3.2 will remove the feature outright.

[radarhere]

Over here @wiredfool points out that current users of Debian are still back on 2.6.1, and that release schedule could possibly jump over a deprecation warning.

[hugovk]

Those deprecation schedules are quite similar and both look fine, I like the quiet/loud/removal of the second.

We could just increase the interval to make sure there's been a Debian/Redhat release for each.

However, as Debian's still on 2.6.1 from October 2014, and if 6+ months is too long for each interval, we could require at least one -- but not necessarily both -- warning releases are made to Debian/Redhat.

[wiredfool]

All deprecations should remain documented, and (in the end state) if they can throw errors that mention the deprecation rather than generic errors, so much the better.

I'm not so into the quiet deprecation. All it seems to do is delay the loud warnings in a way that most people will never see, so it lengthens the less useful phase of deprecation. If we want to push deprecation to the agressive side, then lets do it at the expense of the quiet part.

A year is probably a good time frame for loud deprecation, given how fast we're releasing. Two releases is only 6 months, and if you follow our versioning as semantic versioning, all the releases should be forward compatible with each other. Mostly they are.

Debian Stable is a decent back marker for me -- They're aiming for a year or two between major releases. (And it's generally 6 months between new version freeze and release) If we're giving deprecation warnings back a year or latest debian stable, that should cover 95% of the population. The others are on a varying mix of PIL and old Pillow, and stuff will break.

My goal here is to have less of the threads where "X is broken, but worked in 2.5". Especially if we break Django.

[hugovk]

👍 for: loud deprecation warnings for a year, then removal.