Repository navigation
define our deprecation policy #2924
Description
An update to our versioning scheme is pending in #2910. That PR spawned a necessary discussion about what deprecation policy we should have. This also relates to the question of our release schedule. We can use this issue to figure these things out.
cc @dstansby
Activity
maxrjones commentedon Jun 4, 2026
I think tackling this issue would help a lot in PR and issue reviews that propose eventually removing some functionality. Could we adopt https://numpy.org/neps/nep-0023-backwards-compatibility.html with minor changes to match Zarr-Python?
d-v-b commentedon Jun 4, 2026
that looks good to me! are there any alternatives to use for comparison?
maxrjones commentedon Jun 4, 2026
xarray's backwards compatibility guidance is deliberately judgment-based. it asks contributors to avoid breakage where possible, justify it in the PR when unavoidable, and run a deprecation cycle (warn first, remove later) rather than codifying fixed timelines.
Apache Arrow's arrow-rs deprecation guidelines are a close analogue: minor releases may deprecate but not remove APIs, deprecations are tagged with #[deprecated] and the version they landed in, and removal happens no sooner than two major releases (~6–9 months) later.
maxrjones commentedon Jun 4, 2026
FWIW I like that NumPy's guidance includes a framework for deciding "is this deprecation cycle worth it". I think in Zarr we often have conflicting opinions about the weight of those factors, and it'd be helpful to have something shared.
docs: add a deprecation policy to the contributing guide (zarr-develo…