search

zarr-developers / zarr-python

An implementation of chunked, compressed, N-dimensional arrays for Python.
https://zarr.readthedocs.io
MIT License
1.45k stars 273 forks source link

Doc/v3 migration guide #2102

Open jhamman opened 3 weeks ago

jhamman commented 3 weeks ago

Over the past few weeks, we've had a number of conversations/questions about the policy for backward compatibility, deprecations, and breaking changes with the upcoming 3.0 release. This doc is meant to help us iterate toward common language. In its initial form, it is not complete.

Goals for the text here:

  1. Developers of 2.18 and 3.0 should be able to decide if backward compatibility is a required attribute of a contribution
  2. Users of Zarr should be able to understand if their application will be impacted by the upcoming 3.0 release
  3. Users of Zarr should be able to make a plan for how they will adapt their usage of Zarr after the release
  4. [non-goal] This is not meant to provide a comprehensive listing of the changes to the zarr API

cc @zarr-developers/python-core-devs

TomAugspurger commented 3 weeks ago

One thing that might be helpful: what's the group's tolerance for either compatibility code or deprecations as a way to ease the transition? It sounds like strict backwards compatibility (perhaps with warnings) isn't a goal. Is there tolerance for things like https://github.com/zarr-developers/zarr-python/pull/2098 (e.g. restore some properties to the Group object, loosen the keyword-only requirement for some functions). Likewise for things like "cleaning up internal and user facing APIs", which could be done with a deprecation warning. Even if there isn't tolerance for backwards compatibility shims that really clash with the V3 spec or the current v3 implementation?