Document how to deprecate things

[sergiopaniego]

Summary

Adds a short Deprecations section under the breaking change policy in .claude/docs/INVARIANTS.md. OpenEnv had no written convention for deprecating something, and the next one will likely be done by an agent, which reads this file.

The rule:

• Deprecate before removing: keep it working until a stated release, and warn whoever uses it.
• The warning says when it goes away (the OpenEnv release that removes it) and what to use instead, concrete enough to copy, plus a docs link when the replacement is more than a one-line change.
• 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.
• The docs say the same, with the same version.
• Pre-1.0, 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 it in the release notes.

This follows how TRL handles deprecations, which it has applied since well before its 1.0 (removal version and replacement in every warning, FutureWarning, removal in the announced release). The timeline is shorter than TRL's (it asks for about 5 minor releases for widely used features) because OpenEnv ships roughly one minor a week.

#1276 is the first deprecation that follows it (opencode_env and pi_env, removed in 0.8.0). The two PRs are independent.

The existing openenv_core import shim predates this and uses DeprecationWarning with no removal version; it can be aligned separately.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation
• New environment
• Refactoring

Alignment Checklist

Before submitting, verify:

• I have read .claude/docs/PRINCIPLES.md and this PR aligns with our principles
• I have checked .claude/docs/INVARIANTS.md and no invariants are violated
• I have run /pre-submit-pr (or bash .claude/hooks/lint.sh and tests) and addressed all issues

RFC Status

• Not required (bug fix, docs, minor refactoring)
• RFC exists: #___
• RFC needed (will create before merge)

Test Plan

Docs only (.claude/docs/INVARIANTS.md), no code change.

Claude Code Review

N/A

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation-only change to contributor invariants; no runtime or API behavior is modified in this PR.

Overview
Adds a Deprecations subsection to .claude/docs/INVARIANTS.md so agents and contributors have a written process before removing APIs, CLI flags, or environments.

The new rules require keeping deprecated surface working until a named OpenEnv release, emitting warnings that state removal version and a copy-paste replacement (with docs links when needed), using FutureWarning with stacklevel=2, mirroring the same timeline in user-facing docs, and pre-1.0 waiting at least two minor releases between first warning and removal (longer for heavily used pieces). A Python warnings.warn example is included as the canonical template.

^{Reviewed by Cursor Bugbot for commit be09703. Bugbot is set up for automated code reviews on this repo. Configure here.}

[bot-ci-comment]

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

[cursor]

Alignment Review Report

Automated Checks

• Lint: N/A — uv is not available in this execution environment to run .claude/hooks/lint.sh, but the diff touches only .claude/docs/INVARIANTS.md (no Python files), so usort/ruff are not applicable to this change anyway.
• Debug code: CLEAN — .claude/hooks/check-debug.sh only surfaces pre-existing print/console.print calls and TODOs elsewhere in src/; none originate from this diff, which adds only Markdown.

Open RFCs Context

• RFC 000 (000-project-phases.md) — Status: In Review. Directly relevant: it already states a pre-1.0 breaking-change policy that this PR's new text overlaps with (see conflict below).
• Other RFCs (001, 002, 003, 004, 005, 008, 010, 011, 012) are unaffected by this docs-only change.

Tier 1: Fixes Required

None. The diff is a well-scoped, self-contained addition to .claude/docs/INVARIANTS.md (22 lines, one file). No lint issues, no debug code, no syntax/type errors possible in a Markdown-only change.

Tier 2: Alignment Discussion

Principle Conflicts

None identified. The new "Deprecations" section doesn't touch the Gymnasium API, client/server boundary, reward placement, or the WebSocket/MCP dual-API model from PRINCIPLES.md.

RFC Conflicts

ALIGNMENT FLAG: New pre-1.0 "soft deprecation" requirement contradicts RFC 000's explicit no-soft-deprecation stance

• Principle/RFC at stake: RFC 000 (000-project-phases.md, Status: In Review), section "Our approach towards breaking changes"
• The concern: RFC 000 states: "Until Version 1.0, we plan to move fast and will accept breaking changes if needed (they will be documented and posted into release notes, but we will not put soft deprecation in place until 1.0)." This PR adds to INVARIANTS.md (an invariant that "must NEVER be violated") a formal pre-1.0 soft-deprecation process: keep the old surface working, emit a FutureWarning naming the removal release and replacement, mirror it in docs, and wait at least two minor releases before removal (.claude/docs/INVARIANTS.md:83-103). That is materially stricter than "document breaking changes in release notes" and reads as the opposite of RFC 000's explicit "no soft deprecation until 1.0." Practically this looks like the right evolution — RFC 000 is 000-project-phases and predates the project reaching the scale where the current PR's motivation (#1276 removing opencode_env/pi_env) makes sense — but per the review process, RFC conflicts should be flagged even when they look like the RFC is the one that needs updating, so the two documents stay reconciled rather than silently diverging.
• Suggested reviewer: @Darktex (author of both RFC 000's breaking-change section and the surrounding INVARIANTS.md/PRINCIPLES.md "Breaking Change Policy"/"Key Decisions" sections, per git blame)

Summary

• 0 mechanical issues to fix
• 0 principle-alignment points for human review
• 1 RFC conflict to discuss (pre-1.0 soft-deprecation policy vs. RFC 000's "no soft deprecation until 1.0")

Overall this is a small, clearly-motivated docs change (mirrors TRL's deprecation convention, paired with a real first use in #1276) — the only open item is reconciling the new INVARIANTS.md language with RFC 000's still-"In Review" breaking-change section so the two don't contradict each other going forward.

  

_{Sent by Cursor Automation: Pre-review}

[cursor]

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)