[Backport release/3.0.0] Deprecate legacy physics schema cfgs and writers (#7839)

[ooctipus]

Description

Backports #7839 to release/3.0.0. Legacy physics schema configs and writers emit deprecation warnings naming their schema-fragment replacements, while the existing APIs continue to work. Includes the migration guide, the standard typing_extensions.deprecated implementation, and the original changelog fragments. The fragment-consumer migration from #7838 is already in the release through #7904.

Exact cherry-pick of 5889bae6e8de7a2b5a6e3ff099f82236d251cd19 onto release commit ff22c52891, with no conflicts or source changes. Preserves the source removal target of 3.2, release package versions, and dependency pins.

Validation

292 tests passed locally with PyTorch 2.12:

• Schema deprecation and compatibility tests: 230 passed.
• Schema integration tests: 44 passed.
• Tendon fragment tests: 18 passed.
• uv run --no-sync isaaclab -f: all checks passed with changelog validation against the release base.
• All 13 changed files match the merged source commit; git diff --check passed.

Kit integration tests ran in separate processes on RTX 5090 with Isaac Sim 6.0.1. Release CI uses its pinned Isaac Sim 6.1 image.

Release backport

Targets release/3.0.0 directly; no further backport requested.

[greptile-apps]

Confidence Score: 4/5

The implementation appears safe to merge after correcting the non-blocking but misleading changelog description of existing alias schedule changes.

Findings

1.  Changelog Misstates Alias Changes ▶

Summary

This backport deprecates inheritance-based physics schema configurations and legacy schema writers while retaining their behavior, directs users to composable schema fragments, and adds migration and compatibility coverage.

• Adds construction-time warnings for legacy core, PhysX, and Newton schema configurations.
• Adds call-time warnings for legacy schema writers while preserving nested traversal and internal delegation.
• Documents complete fragment replacements and spawner-level replacements for non-USD fields.
• Adds kitless and integration tests for warning behavior, compatibility, shims, and tendon fragments.
• The changelog currently misstates that several aliases are unaffected even though their removal warnings change.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A[Legacy PropertiesCfg construction] --> B[DeprecationWarning]
    B --> C[Existing legacy behavior retained]
    B --> D[Migration guidance]
    D --> E[Core USD schema fragments]
    D --> F[PhysX schema fragments]
    D --> G[Newton and MuJoCo fragments]
    E --> H[Spawner fragment lists]
    F --> H
    G --> H
    I[Legacy define or modify writer] --> J[DeprecationWarning]
    J --> K[Existing nested writer behavior]
    J --> L[Fragment-based apply writer]

Loading

_{Reviews (1) · Last reviewed commit: "Deprecate the legacy physics schema cfgs..."}

[greptile-apps]

Changelog Misstates Alias Changes

The changelog says material and tendon aliases are unaffected, but this PR changes their runtime removal warnings from 3.1 to 3.2. It similarly calls deformable configs unaffected while changing the warnings for three deformable aliases. Please document these schedule changes or revert them so users receive an accurate account of the existing deprecations modified by this release.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[isaaclab-review-bot]

Isaac Lab Review Bot

The backport preserves the legacy schema cfg and writer implementations while adding deprecation warnings and fragment migration guidance. Two migration instructions need correction: mesh-collision’s replacement writer does not accept prim-path expressions or preserve subtree traversal, and single-fragment spawner replacements should not be presented as lists.

• Design and architecture: The decorator ordering keeps the existing apply_nested traversal inside deprecated writer wrappers, while internal calls through __wrapped__ avoid duplicate warnings. The shared cfg deprecation helper is consistently reused across core, PhysX, and Newton; the remaining concerns are confined to migration guidance rather than the compatibility architecture.
• API: The migration guide incorrectly generalizes all replacement apply_* writers as accepting prim-path expressions: apply_mesh_collision_properties resolves one exact path with GetPrimAtPath. Deprecation messages also advertise list-wrapped replacements such as [MassCfg(...)] where the repository contract requires a bare fragment for a single-fragment spawner slot.
• Implementation: The compatibility paths retain dataclass constructors and helpers, field-alias forwarding, and legacy subtree traversal, with tests consistently using inspect.unwrap. Documentation and warning text should be aligned with the actual mesh-collision writer signature and single-fragment slot representation before merge.

Minor fixes needed. Posted 2 actionable findings inline.

Automated review; human maintainers own approval decisions.

[isaaclab-review-bot]

🟡 Warning · Api — Mesh-collision writer takes exact prim path

This states every apply_* replacement takes a prim-path expression that can author a whole subtree, and the table lists apply_mesh_collision_properties as the replacement for the mesh-collision writers. That function takes a single prim_path, resolves it with stage.GetPrimAtPath, and raises ValueError on an invalid path, so a migrated regex fails and the legacy subtree traversal is lost. Qualify this writer here and in the changelog.

[isaaclab-review-bot]

🟡 Warning · Api — Single-fragment replacements advertised as lists

The new warnings wrap a single replacement fragment in a list ([MassCfg(...)], and likewise for MeshCollisionBaseCfg, ArticulationRootBaseCfg, and the Physx*Mesh cooking classes). The repository fragment rule is a bare fragment for a single instance and a list only for multiple fragments; list form forces callers to select the owning fragment before field access or replace(). This changelog also says "Replace MassPropertiesCfg with MassCfg". Emit the bare form for single-fragment replacements.

[StafaH]

run-ci