Skip to content

Document how to deprecate things #1277

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
burtenshaw merged 2 commits into from
Sep 30, 2026
Merged

Document how to deprecate things #1277

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
27e6db3
Document how to deprecate things
sergiopaniego Sep 30, 2026
be09703
Merge branch 'main' into docs-deprecation-policy
burtenshaw Sep 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions .claude/docs/INVARIANTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

@cursor cursor Bot Sep 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ALIGNMENT FLAG: This pre-1.0 timing requirement ("at least two minor releases between warning and removal") formalizes soft deprecation before 1.0.

  • RFC at stake: RFC 000 (Status: In Review) says: "we will not put soft deprecation in place until 1.0."
  • The concern: INVARIANTS.md says these rules "must NEVER be violated," so this section now mandates exactly the soft-deprecation process RFC 000 says won't exist pre-1.0. Worth reconciling the two docs (or updating RFC 000's still-open breaking-change section) so they don't silently disagree.
  • Suggested reviewer: @Darktex (author of RFC 000's breaking-change section and this file's surrounding policy)


## Violation Response

If you identify a potential invariant violation:
Expand Down
Loading