Skip to content

Commit 84a1f49

Browse files
d-v-bclaude
andcommitted
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]>
1 parent a274377 commit 84a1f49

2 files changed

Lines changed: 9 additions & 8 deletions

File tree

File renamed without changes.

‎docs/contributing.md‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -459,7 +459,7 @@ If an existing Zarr format version changes, or a new version of the Zarr format
459459

460460
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.
461461

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.
463463

464464
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.
465465

@@ -473,32 +473,33 @@ A deprecation cycle has a real cost: every user of the affected API must eventua
473473
- **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.
474474
- **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.
475475

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.
477477

478478
#### How to deprecate
479479

480480
Once a deprecation is decided, it must follow these steps so that users get a consistent, actionable signal:
481481

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.
485485
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.
486486

487487
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.
488488

489489
#### How long a deprecation lasts
490490

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).
492492

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.
494494

495495
#### Exceptions
496496

497497
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:
498498

499499
- **Security fixes and data-corruption bugs**, where continuing the old behavior actively harms users.
500500
- **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.
502503

503504
## Experimental API policy
504505

0 commit comments

Comments
 (0)