From 27e6db390a1d298ec17339a62e1b47fb25b5d1d7 Mon Sep 17 00:00:00 2001 From: sergiopaniego Date: Wed, 30 Sep 2026 12:31:56 +0200 Subject: [PATCH] Document how to deprecate things A short deprecation policy under the breaking change policy: warn with the removal version and a concrete replacement, use FutureWarning so users actually see it, mirror it in the docs, and leave at least two minor releases before removing. --- .claude/docs/INVARIANTS.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/.claude/docs/INVARIANTS.md b/.claude/docs/INVARIANTS.md index 52ca3d3938..5e85ebec22 100644 --- a/.claude/docs/INVARIANTS.md +++ b/.claude/docs/INVARIANTS.md @@ -80,6 +80,28 @@ These invariants must NEVER be violated. If a change would violate them, stop an - MINOR: New features, backward compatible - PATCH: Bug fixes only +### Deprecations + +Before removing an API, CLI flag, or environment, deprecate it first: keep it working until a stated release and warn whoever uses it. + +The warning must say: + +- **When it goes away**: the OpenEnv release that removes it. +- **What to use instead**: concrete enough to copy (the new import, call, or command), plus a docs link when the replacement is more than a one-line change. + +```python +warnings.warn( + "`foo_env` is deprecated and will be removed in OpenEnv 0.8.0. " + "Use `bar_env` instead: `BarFactory(server_url)`. See https://...", + FutureWarning, + stacklevel=2, +) +``` + +- Use `FutureWarning`, not `DeprecationWarning`. Python hides `DeprecationWarning` unless it is raised from `__main__`, so users importing from a module or a notebook would never see it. +- Say the same in the docs (README, doc page, tutorials), with the same version. +- Pre-1.0, leave at least two minor releases between the first release that warns and the removal, more for widely used pieces. Remove in the announced release, and list the removal in its release notes. + ## Violation Response If you identify a potential invariant violation: