Deprecation plan while transitioning to v3

Unless I’m mistaken we’ve not yet explicitly discussed how to transition from v2 to v3. Or it has been so long ago that I forgot 😃

As a first point, I like the idea of having an imageio.v2 and imageio.v3 namespace. My suggestion would be to actually make them modules so one can do e.g. from imageio.v3 import imread.

As for the transition, I see ~two~ three possible routes:

A) With the v3.0 release we put the v3 functions in the imageio root namespace instead of the v2 functions. Maybe some compatibility stuff for a while. This may feel clean, but I fear can also be very disruptive, because although imread() will behave the same in like 95% of use-cases, it may not in the other 5%.

B) A softer approach would be to steer people into using import imageio.v3 as iio. Then, after a while we can add deprecation warnings to the v2 functions, and after yet another year or so we can kill off the v2 code.

C) We can change the name of imageio to imageio3, so people can actually use both side-by-side. Now that I’m writing this I think we discussed this earlier, and IIRC we decided against it.

[jni]

How do you go about advertising such changes?

Oh that is fun! We will release skimage2 as a separate package. When we release it, we will simultaneously release version 0.(x+1) of scikit-image, which is identical to v0.x with the only difference being an import-time warning that says, skimage2 is out, the transition guide is here (link), if you want to silence this warning, migrate to skimage2 or pin your dependency to skimage<=0.x.

[FirefoxMetzger]

I still feel strongly that we should take care to minimize the burden/surprise for existing users, and allow them to transition in their own time.

We are still in agreement on this point 😃 I think the main difference is what we see as an adequate amount for “in their own time”. I put this at around 6 months, whereas you put it somewhere north of 1.5 years.

I’d also like to bring up (again) the idea of creating a new package

On top of the maintenance burden, there is also the everpresent “curse of mylib2”. You make a new package which ought to become the new version and instead, it splits your community in half, with 50% being early adopters and enthusiasts and the other 50% never updating, because of some reason. It happened to angular/angular2, ros/ros2, and many others that went down that path. Of all the projects I am aware of that went down that path, all ended up worse than before. Maybe you know of some success stories? (That’s one of the big reasons why I am wary of this road.)

Another point is that, if you really think about it, the breaking changes aren’t actually that many. It’s just imread which changes its output, and us deciding on what should happen with the old API functions. Most other things should be resolvable in a backward-compatible way; especially considering the new format_hint feature (https://github.com/imageio/imageio/pull/734), which can take most (all?) of the v2 format= behavior that isn’t plugin related. We can simply run a deprecation cycle on the kwarg and ask people to rename it to format_hint or plugin as needed. The output change also isn’t too bad, considering that we rarely hear about metadata issues, and that we didn’t have a clear policy on that to begin with.

The top-level namespace needs sorting out, but I am still confident that we can find a suitable solution. How about we keep the top-level functions indefinitely (no deprecation) and give it a dedicated name, say “meta”? We would then have

• import imageio as iio --> imports the meta API which is a conglomerate of all API versions (with the behavior of the latest one replacing the previous one in the case of a name collision)
• import imageio.v3 as iio --> v3 API only
• import imageio.v2 as iio --> v2 API only (albeit using the new backends)
• from imageio import Image --> OOP Image API (tbd)

Except for Image all of these would be tight wrappers around iio.imopen, so there would be little maintenance burden and we can keep them alive indefinitely.