Add deprecation warnings to v2 code that won't work in v3

[jeromekelleher]

As discussed in #1849, I think it would be very helpful for users who are not necessarily keeping up to date with Zarr development to get some warning that their code is going to break soon. A good way of helping people to prepare would be to add deprecation warnings to all of the v2 methods that are expected to break in v3 (Some of this was done in #1801 for stores, which is great). Ideally, this warning would have helpful messages saying how to port your code to v3 compatible versions, or at worst saying that you need to pin your Zarr dependency to < 3 ASAP.

I know this feels like a lot of not very exciting work, but I'm really worried that we're going to end up with messy transition like Python 2 to Python 3, where users who don't know much about Zarr get confusing messages, and end up with the (very very false!) impression that Zarr is a bit flaky and not worth the effort.

As it stands, I'm not at all clear what bits of my code are about to break and what I'm going to need to do to update to v3, and I assume that I'm one of the more tuned-in downstream users.

[jni]

For reference, we had a plan for making the skimage 0.x -> 1.0 transition relying on an import-time warning:

https://scikit-image.org/docs/stable/skips/3-transition-to-v1.html#implementation

Summary for zarr:

• finish migration guide
• release the final 2.x series feature release, zarr 2.(n).0
• immediately release zarr 2.(n+1).0, which is the same release but with an import warning: zarr 3 is going to be released soon, either migrate using this guide (link) or make sure you pin to <=2.(n) to silence this warning.

I would actually suggest modifying the plan to release zarr2 and ask users to depend on that package instead of pinning. This will make it possible to install packages A and B in the same env when A depends on zarr2 (and is not updated) and B depends on zarr v3.x.

For skimage, it was decided that the package name wasn't worth upsetting however many users it would upset — we will release skimage2. But since it looks like zarr will keep the package name, I suggest the above approach.

[jeromekelleher]

That all sounds very sensible to me @jni. I don't really have a sense of whether I think the zarr2 package is worth it or not, but I'll shut up now until the migration guide is ready 😉

Thanks for all the great work in making Zarr 3 a reality all!

[jhamman]

A useful exercise that we could use some help with is trying to define the "public" Zarr API in v2. Is it the whole library, obviously not, but we don't have any easy way to say what the bounds are. Once we have that defined, it will be much easier to decide what we need to slap deprecation warnings on, and what we don't.

And +1 on the migration guide. I'm happy to start this -- but I would like to wait until after we ship the alpha release candidate.

[jeromekelleher]

A useful exercise that we could use some help with is trying to define the "public" Zarr API in v2

Everything that's documented in the API reference?

[dstansby]

Any more thoughts on the plan here from @zarr-developers/python-core-devs? Deprecating API seems like a pretty major thing that needs to get released with a long enough lead time for users to adjust to the warnings (>= 3 months?) before a v3 release.

I quite like the solution that Tom Caswell described at https://mail.python.org/archives/list/scikit-image@python.org/message/GFXBQYKDACDCH7BGNEGOU7LKHR2LPFX6/, which would be having a zarr.v2 and zarr.v3 namespace, encouraging users to change imports now to zarr.v2 and then releasing a new zarr.v3 namespace with version 3.0.

[jhamman]

I think we have done what we can in terms of deprecations in 2.18. Remaining API changes are either a) going to be managed via a deprecation cycle in 3.0 or b) unavoidable/intentional.