You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 84a1f49
Browse filesBrowse the repository at this point in the historyBrowse files
docs: align the deprecation policy with the versioning section and the code
Review follow-ups on the deprecation policy:
- Explain who each warning class reaches: DeprecationWarning is hidden
outside __main__ and test runners, FutureWarning is shown to everyone,
which a behavior change needs.
- Drop the "release first appeared in" requirement from the message; the
release type is decided at release time under EffVer.
- Widen the recently-introduced-API exception to match the versioning
section, and make the experimental promotion re-export explicitly exempt.
- Extend the minimum period to behavior changes, name raised exceptions as
observable behavior, and note that a removal in a minor release is not
SemVer (review threads).
- Rename the changelog fragment to the PR number.
Assisted-by: ClaudeCode:claude-fable-5-1
Co-Authored-By: Claude Fable 5.1 <[email protected]>
Copy file name to clipboardExpand all lines: docs/contributing.md
+9-8Lines changed: 9 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -459,7 +459,7 @@ If an existing Zarr format version changes, or a new version of the Zarr format
459
459
460
460
Our versioning policy (above) commits us to minimizing the effort users spend upgrading. A deprecation cycle is the main tool we use to honor that commitment: rather than removing or changing public behavior abruptly, we first ship a release that keeps the old behavior working while warning that it is going away, and only remove it in a later release. This section defines when a deprecation cycle is required, how to decide whether a removal is worth it, and the concrete steps a deprecation must follow.
461
461
462
-
This policy governs the user-facing Python API of `zarr-python`: importable names, function and method signatures, and observable runtime behavior. It does not govern the Zarr data format, whose compatibility is described under [Data format compatibility](#data-format-compatibility) above, nor the `zarr.experimental` namespace, which is governed by the [Experimental API policy](#experimental-api-policy) below. Private API (names prefixed with `_`, and anything not documented as public) may change at any time without a deprecation cycle.
462
+
This policy governs the user-facing Python API of `zarr-python`: importable names, function and method signatures, the exceptions raised, and other observable runtime behavior. It does not govern the Zarr data format, whose compatibility is described under [Data format compatibility](#data-format-compatibility) above, nor the `zarr.experimental` namespace, which is governed by the [Experimental API policy](#experimental-api-policy) below. Private API (names prefixed with `_`, and anything not documented as public) may change at any time without a deprecation cycle.
463
463
464
464
Any backwards-incompatible change to public API -- removing a name, changing a signature in a non-additive way, or changing observable behavior -- requires a deprecation cycle unless it qualifies for one of the [exceptions](#exceptions) listed below.
465
465
@@ -473,32 +473,33 @@ A deprecation cycle has a real cost: every user of the affected API must eventua
473
473
-**Who benefits.** Benefits can include improved functionality, usability, and performance for users, as well as lower maintenance cost and better future extensibility for developers. A change that gives users something they want is a stronger case than one that benefits only maintainers, since users pay the migration cost either way.
474
474
-**Whether the goal can be met without removal.** Often a refactor, an alias, or an additive change achieves the same end without breaking anyone. Prefer those. Removing public API is never free; the deprecation cycle is the price, and it is mandatory.
475
475
476
-
If, after weighing these factors, a removal is not clearly worthwhile, prefer to keep the API. A deprecation warning is a commitment to remove: if you only want to steer users away from an API without removing it, say so in its documentation rather than emitting a warning. Conversely, do not leave a decision to remove an API indefinitely deferred: a vague intention to "eventually" break something is itself a form of technical debt. Either commit to the deprecation and begin the cycle, or decide to keep the API and design around it.
476
+
If, after weighing these factors, a removal is not clearly worthwhile, prefer to keep the API. A deprecation warning is a commitment to change or remove: if you only want to steer users away from an API without removing it, say so in its documentation rather than emitting a warning. Conversely, do not leave a decision to remove an API indefinitely deferred: a vague intention to "eventually" break something is itself a form of technical debt. Either commit to the deprecation and begin the cycle, or decide to keep the API and design around it.
477
477
478
478
#### How to deprecate
479
479
480
480
Once a deprecation is decided, it must follow these steps so that users get a consistent, actionable signal:
481
481
482
-
1.**Emit a warning at runtime.** Raise `zarr.errors.ZarrDeprecationWarning` for an API that will be *removed*. Use `zarr.errors.ZarrFutureWarning` instead when behavior will *change* rather than disappear (for example, a default value that will change), since `FutureWarning` is shown to end users by default. The [`typing_extensions.deprecated`](https://typing-extensions.readthedocs.io/en/latest/#deprecated) decorator is the preferred way to deprecate whole functions, methods, and classes. When calling `warnings.warn` directly, set `stacklevel` so the warning points at the caller's code rather than zarr internals.
483
-
2.**Write an actionable message.** The warning message must state the release the deprecation first appeared in, the planned removal (a specific version if known, otherwise "a future release"), and the migration path -- what the user should do instead. A deprecation warning with no replacement guidance is incomplete.
484
-
3.**Document it.**Mark the deprecation in the docstring (via the `deprecated` decorator or a "Deprecated" admonition) so it appears in the rendered API documentation, and update any affected user-guide prose.
482
+
1.**Emit a warning at runtime.** Raise `zarr.errors.ZarrDeprecationWarning` for an API that will be *removed*. Use `zarr.errors.ZarrFutureWarning` instead when behavior will *change* rather than disappear (for example, a default value that will change). The distinction is about who needs to see the warning: Python hides `DeprecationWarning` by default except in `__main__` and under test runners, so a removal warning reaches the authors of the code that calls the deprecated API, whereas `FutureWarning` is shown to everyone, which a behavior change needs because it alters results without any change to the user's code. The [`typing_extensions.deprecated`](https://typing-extensions.readthedocs.io/en/latest/#deprecated) decorator is the preferred way to deprecate whole functions, methods, and classes. When calling `warnings.warn` directly, set `stacklevel` so the warning points at the caller's code rather than zarr internals.
483
+
2.**Write an actionable message.** The warning message must state the planned removal or change (a specific version if known, otherwise "a future release") and the migration path -- what the user should do instead. A deprecation warning with no replacement guidance is incomplete.
484
+
3.**Document it.**Add a "Deprecated" admonition to the docstring, stating the same removal target and migration path as the warning, so the deprecation appears in the rendered API reference, and update any affected user-guide prose.
485
485
4.**Add a changelog entry.** Add a `removal` changelog fragment in `changes/` (for example, `changes/1234.removal.md`) so the deprecation is announced under "Deprecations and Removals" in the release notes. When the API is finally removed, add a second `removal` fragment for that release.
486
486
487
487
When an API is being replaced rather than simply dropped, deprecate the old name and introduce its replacement in a single step, rather than repeatedly adjusting the same signature across releases. Users should have to migrate only once.
488
488
489
489
#### How long a deprecation lasts
490
490
491
-
A deprecated API must remain available, emitting its warning, for **at least 6 months and at least one minor release** before it is removed. These are minimums, not targets: for widely-used API, prefer a longer cycle, and communicate the upcoming removal beyond the warning itself (for example, in release notes or a migration guide).
491
+
A deprecated API must remain available, emitting its warning, for **at least 6 months and at least one minor release** before it is removed. The same minimum applies to a behavior change announced with `ZarrFutureWarning`: the old behavior stays the default, with the warning, for at least that long before the change takes effect. These are minimums, not targets: for widely-used API, prefer a longer cycle, and communicate the upcoming removal beyond the warning itself (for example, in release notes or a migration guide).
492
492
493
-
The removal itself is a backwards-incompatible change, and is classified under our [versioning policy](#versioning) by the upgrade effort it imposes -- a `major` release for the removal of widely-used API, a `minor` release when the impact is genuinely small. The deprecation period, not the release type, is the guarantee users rely on: a removal is only permitted once the minimum period has elapsed, regardless of which release it lands in.
493
+
The removal itself is a backwards-incompatible change, and is classified under our [versioning policy](#versioning) by the upgrade effort it imposes -- a `major` release for the removal of widely-used API, a `minor` release when the impact is genuinely small. This differs from [Semantic Versioning](https://semver.org/), under which any removal would require a `major` release; the [versioning policy](#versioning) above explains why. The deprecation period, not the release type, is the guarantee users rely on: a removal is only permitted once the minimum period has elapsed, regardless of which release it lands in.
494
494
495
495
#### Exceptions
496
496
497
497
A full deprecation cycle may be shortened or skipped in these cases. When it is, explain why in the pull request and the changelog entry:
498
498
499
499
-**Security fixes and data-corruption bugs**, where continuing the old behavior actively harms users.
500
500
-**Changes forced by the Zarr format specification**, which are governed by [Data format compatibility](#data-format-compatibility) and may move faster during a format transition.
501
-
-**Recently introduced API** that has not yet appeared in a stable release, which can still be changed freely, and **experimental API**, which is exempt and governed by the [Experimental API policy](#experimental-api-policy).
501
+
-**Recently introduced API**, which has had little time to be adopted. API that has not yet appeared in a release can be changed freely. API that appeared in a recent release may be changed in a `minor` release with a shortened cycle, as the [versioning policy](#versioning) allows, when the number of affected users is small because the API is new.
502
+
-**Experimental API**, which is exempt and governed by the [Experimental API policy](#experimental-api-policy). This includes the deprecated re-export left in `zarr.experimental` when a feature is promoted to stable, which that policy keeps for one minor release.
0 commit comments