Fix migration syntax to Hydra-style key=value selectors

The cartpole deprecation warnings, env_cfg docstrings, regression-test
fixtures, and changelog fragment all referenced the typed preset CLI
as ``--presets=NAME`` / ``--physics`` / ``--renderer``. The preset CLI
landed with Hydra-style ``key=value`` tokens (no leading dashes); the
dashed form was an intermediate iteration that did not ship.

Corrects every touchpoint so users following the deprecation warning
copy a command that actually parses:

* runtime DeprecationWarning messages in the 4 consolidated env_cfg
  modules now say ``presets=<name>`` (still ``--task=`` since that is
  a real argparse flag);
* test_cartpole_preset_deprecations fixtures and docstrings updated to
  match;
* docstrings/comments in the env_cfg modules and the showcase
  __init__.py;
* changelog fragment.

Author: hujc7

source/isaaclab_tasks/changelog.d/jichuanh-cartpole-presets.minor.rst

@@ -6,18 +6,18 @@ Added
   (``rgb``, ``depth``, ``albedo``, ``semantic_segmentation``,
   ``simple_shading_constant_diffuse``, ``simple_shading_diffuse_mdl``,
   ``simple_shading_full_mdl``), renderer backend, and physics backend at
-  runtime via the typed preset CLI flags (``--physics``, ``--renderer``,
-  ``--presets``).
+  runtime via the Hydra-style preset selectors from #5587 (``physics=NAME``,
+  ``renderer=NAME``, ``presets=NAME[,NAME,...]``; no leading dashes).
 * Added :data:`Isaac-Cartpole-Camera-v0` -- consolidated manager-based
   perception cartpole task. Selects the observation pipeline
   (``rgb``, ``depth``, ``resnet18``, ``theia_tiny``) and physics backend at
-  runtime via ``--presets`` / ``--physics``. The two ``rl_games`` agent
+  runtime via ``presets=`` / ``physics=``. The two ``rl_games`` agent
   yamls live under ``rl_games_cfg_entry_point`` (image policy, default) and
   ``rl_games_feature_cfg_entry_point`` (pretrained-feature policy); pick via
   ``--agent <name>``.
 * Added :data:`Isaac-Cartpole-Showcase-Direct-v0` -- consolidated
   proprioceptive showcase task that selects the (observation, action) gym
-  space combination at runtime via ``--presets=<obs>_<action>``. All 15
+  space combination at runtime via ``presets=<obs>_<action>``. All 15
   combinations of ``{box, discrete, multidiscrete, dict, tuple}`` observation
   and ``{box, discrete, multidiscrete}`` action are registered as variants.
   The matching ``skrl`` policy yaml is exposed as
@@ -30,28 +30,28 @@ Deprecated
 ^^^^^^^^^^
 
 * Deprecated the per-variant Direct-backend perception task IDs in favor of
-  :data:`Isaac-Cartpole-Camera-Direct-v0` with ``--presets=<name>``. Each
+  :data:`Isaac-Cartpole-Camera-Direct-v0` with ``presets=<name>``. Each
   retired ID still loads but emits a :class:`DeprecationWarning` pointing at
   the new invocation:
 
   * ``Isaac-Cartpole-Camera-Presets-Direct-v0`` -> ``Isaac-Cartpole-Camera-Direct-v0``
-  * ``Isaac-Cartpole-RGB-Camera-Direct-v0`` -> ``Isaac-Cartpole-Camera-Direct-v0 --presets=rgb``
-  * ``Isaac-Cartpole-Depth-Camera-Direct-v0`` -> ``Isaac-Cartpole-Camera-Direct-v0 --presets=depth``
-  * ``Isaac-Cartpole-Albedo-Camera-Direct-v0`` -> ``Isaac-Cartpole-Camera-Direct-v0 --presets=albedo``
-  * ``Isaac-Cartpole-SimpleShading-Constant-Camera-Direct-v0`` -> ``Isaac-Cartpole-Camera-Direct-v0 --presets=simple_shading_constant_diffuse``
-  * ``Isaac-Cartpole-SimpleShading-Diffuse-Camera-Direct-v0`` -> ``Isaac-Cartpole-Camera-Direct-v0 --presets=simple_shading_diffuse_mdl``
-  * ``Isaac-Cartpole-SimpleShading-Full-Camera-Direct-v0`` -> ``Isaac-Cartpole-Camera-Direct-v0 --presets=simple_shading_full_mdl``
+  * ``Isaac-Cartpole-RGB-Camera-Direct-v0`` -> ``Isaac-Cartpole-Camera-Direct-v0 presets=rgb``
+  * ``Isaac-Cartpole-Depth-Camera-Direct-v0`` -> ``Isaac-Cartpole-Camera-Direct-v0 presets=depth``
+  * ``Isaac-Cartpole-Albedo-Camera-Direct-v0`` -> ``Isaac-Cartpole-Camera-Direct-v0 presets=albedo``
+  * ``Isaac-Cartpole-SimpleShading-Constant-Camera-Direct-v0`` -> ``Isaac-Cartpole-Camera-Direct-v0 presets=simple_shading_constant_diffuse``
+  * ``Isaac-Cartpole-SimpleShading-Diffuse-Camera-Direct-v0`` -> ``Isaac-Cartpole-Camera-Direct-v0 presets=simple_shading_diffuse_mdl``
+  * ``Isaac-Cartpole-SimpleShading-Full-Camera-Direct-v0`` -> ``Isaac-Cartpole-Camera-Direct-v0 presets=simple_shading_full_mdl``
 
 * Deprecated the per-variant manager-based perception task IDs in favor of
-  :data:`Isaac-Cartpole-Camera-v0` with ``--presets=<name>``:
+  :data:`Isaac-Cartpole-Camera-v0` with ``presets=<name>``:
 
-  * ``Isaac-Cartpole-RGB-v0`` -> ``Isaac-Cartpole-Camera-v0 --presets=rgb``
-  * ``Isaac-Cartpole-Depth-v0`` -> ``Isaac-Cartpole-Camera-v0 --presets=depth``
-  * ``Isaac-Cartpole-RGB-ResNet18-v0`` -> ``Isaac-Cartpole-Camera-v0 --presets=resnet18``
-  * ``Isaac-Cartpole-RGB-TheiaTiny-v0`` -> ``Isaac-Cartpole-Camera-v0 --presets=theia_tiny``
+  * ``Isaac-Cartpole-RGB-v0`` -> ``Isaac-Cartpole-Camera-v0 presets=rgb``
+  * ``Isaac-Cartpole-Depth-v0`` -> ``Isaac-Cartpole-Camera-v0 presets=depth``
+  * ``Isaac-Cartpole-RGB-ResNet18-v0`` -> ``Isaac-Cartpole-Camera-v0 presets=resnet18 --agent rl_games_feature_cfg_entry_point``
+  * ``Isaac-Cartpole-RGB-TheiaTiny-v0`` -> ``Isaac-Cartpole-Camera-v0 presets=theia_tiny --agent rl_games_feature_cfg_entry_point``
 
 * Deprecated the 15 per-shape proprioceptive showcase task IDs in favor of
-  :data:`Isaac-Cartpole-Showcase-Direct-v0` with ``--presets=<obs>_<action>``
+  :data:`Isaac-Cartpole-Showcase-Direct-v0` with ``presets=<obs>_<action>``
   and ``--agent skrl_<obs>_<action>_cfg_entry_point``. Each retired ID
   (``Isaac-Cartpole-Showcase-{Box,Discrete,MultiDiscrete,Dict,Tuple}-{Box,Discrete,MultiDiscrete}-Direct-v0``)
   still loads but emits a :class:`DeprecationWarning` pointing at the new
@@ -60,4 +60,4 @@ Deprecated
 * Deprecated the 9 per-shape camera-based showcase task IDs in favor of
   :data:`Isaac-Cartpole-Camera-Showcase-Direct-v0`. Each retired ID
   (``Isaac-Cartpole-Camera-Showcase-{Box,Dict,Tuple}-{Box,Discrete,MultiDiscrete}-Direct-v0``)
-  emits a ``DeprecationWarning`` with the matching ``--presets=<obs>_<action>``.
+  emits a ``DeprecationWarning`` with the matching ``presets=<obs>_<action>``.

source/isaaclab_tasks/isaaclab_tasks/direct/cartpole/cartpole_camera_presets_env_cfg.py

@@ -58,7 +58,7 @@ class CartpoleTiledCameraCfg(CameraCfg):
 
     # Per-variant 180-degree offset -- matches the historical
     # CartpoleAlbedoCameraEnvCfg / CartpoleSimpleShading{Constant,Diffuse,Full}CameraEnvCfg
-    # so the deprecated task IDs and ``--presets=<name>`` against the consolidated
+    # so the deprecated task IDs and ``presets=<name>`` against the consolidated
     # task return identical cfg shape (including camera orientation).
     _ROTATED_OFFSET = CameraCfg.OffsetCfg(pos=(-5.0, 0.0, 2.0), rot=(1.0, 0.0, 0.0, 0.0), convention="world")
     albedo = CartpoleTiledCameraCfg(data_types=["albedo"], offset=_ROTATED_OFFSET)
@@ -133,7 +133,7 @@ class BaseCartpoleCameraEnvCfg(DirectRLEnvCfg):
 # through these factories instead of their old per-variant cfg classes. Each
 # factory emits a :class:`DeprecationWarning` pointing at the consolidated
 # :data:`Isaac-Cartpole-Camera-Direct-v0` task with the equivalent
-# ``--presets=<name>`` invocation, then returns the corresponding variant of
+# ``presets=<name>`` invocation, then returns the corresponding variant of
 # :class:`CartpoleCameraPresetsEnvCfg` so existing behavior is preserved.
 
 
@@ -158,7 +158,7 @@ def _deprecated_factory(old_task_id: str, preset_name: str | None = None):
 
     def factory():
         new_id = "Isaac-Cartpole-Camera-Direct-v0"
-        tail = f"--task={new_id}" + (f" --presets={preset_name}" if preset_name else "")
+        tail = f"--task={new_id}" + (f" presets={preset_name}" if preset_name else "")
         warnings.warn(
             f"Task '{old_task_id}' is deprecated and will be removed in a future release. Use {tail}.",
             DeprecationWarning,
@@ -171,7 +171,7 @@ def factory():
         # this, the shim leaves ``tiled_camera`` as the nested PresetCfg whose
         # default is rgb -- so e.g. the deprecated albedo task would load the
         # albedo observation_space with an rgb data_types camera, and a stray
-        # ``--presets=X`` would also override the camera independently of the
+        # ``presets=X`` would also override the camera independently of the
         # root. ``MultiDataTypeCartpoleTiledCameraCfg`` exposes the same set of
         # variant names as ``CartpoleCameraPresetsEnvCfg``, so the same key
         # selects both consistently.

source/isaaclab_tasks/isaaclab_tasks/direct/cartpole_showcase/cartpole/__init__.py

@@ -19,7 +19,7 @@
 # space combination via the preset CLI (#5587). Each of the 15 retired IDs
 # below routes through a deprecation factory in
 # ``cartpole_showcase_presets_env_cfg`` that points at this task with the
-# equivalent ``--presets=<obs>_<action>``. The default skrl yaml matches the
+# equivalent ``presets=<obs>_<action>``. The default skrl yaml matches the
 # canonical ``box_box`` shape; for other variants pass the matching
 # ``--agent skrl_<obs>_<action>_cfg_entry_point``.
 gym.register(
@@ -54,7 +54,7 @@
 # -- Deprecated aliases --------------------------------------------------------
 # Each retired task ID routes its env_cfg_entry_point through a deprecation
 # factory in cartpole_showcase_presets_env_cfg that emits a
-# DeprecationWarning naming the consolidated task + equivalent --presets value.
+# DeprecationWarning naming the consolidated task + equivalent presets= value.
 
 ###
 # Observation space as Box

source/isaaclab_tasks/isaaclab_tasks/direct/cartpole_showcase/cartpole/cartpole_showcase_presets_env_cfg.py

@@ -7,7 +7,7 @@
 
 Wraps the 15 per-(observation, action) cfg classes in :mod:`cartpole_env_cfg`
 into a single :class:`PresetCfg` so the ``Isaac-Cartpole-Showcase-Direct-v0``
-task can switch between them at runtime via ``--presets=<obs>_<action>``
+task can switch between them at runtime via ``presets=<obs>_<action>``
 (the typed preset CLI from #5587). Each retired showcase task ID routes its
 ``env_cfg_entry_point`` through one of the deprecation factories below.
 
@@ -73,7 +73,7 @@ class CartpoleShowcasePresetsEnvCfg(PresetCfg):
     """Proprioceptive cartpole showcase with selectable observation/action space.
 
     Each variant attribute is an instance of an existing per-shape cfg class.
-    The hydra resolver picks one based on the ``--presets=<name>`` CLI token;
+    The hydra resolver picks one based on the ``presets=<name>`` CLI token;
     the default is ``box_box`` (matching the canonical cartpole shape).
     """
 
@@ -107,7 +107,7 @@ def _deprecated_factory(old_task_id: str, preset_name: str):
     retired showcase task ID. On invocation it emits a
     ``DeprecationWarning`` pointing at the consolidated
     ``Isaac-Cartpole-Showcase-Direct-v0`` task with the equivalent
-    ``--presets=<preset_name>``, then returns a fresh instance of the
+    ``presets=<preset_name>``, then returns a fresh instance of the
     corresponding per-shape cfg class so the retired task keeps loading a
     working cfg until removal.
 
@@ -123,7 +123,7 @@ def factory():
         new_id = "Isaac-Cartpole-Showcase-Direct-v0"
         warnings.warn(
             f"Task '{old_task_id}' is deprecated and will be removed in a future release. "
-            f"Use --task={new_id} --presets={preset_name}.",
+            f"Use --task={new_id} presets={preset_name}.",
             DeprecationWarning,
             stacklevel=2,
         )

source/isaaclab_tasks/isaaclab_tasks/direct/cartpole_showcase/cartpole_camera/cartpole_camera_showcase_presets_env_cfg.py

@@ -7,7 +7,7 @@
 
 Wraps the 9 per-(observation, action) cfg classes in :mod:`cartpole_camera_env_cfg`
 into a single :class:`PresetCfg` so the ``Isaac-Cartpole-Camera-Showcase-Direct-v0``
-task can switch between them at runtime via ``--presets=<obs>_<action>``.
+task can switch between them at runtime via ``presets=<obs>_<action>``.
 Each retired showcase task ID routes its ``env_cfg_entry_point`` through one
 of the deprecation factories below. The companion ``skrl`` policy yaml is
 variant-specific; all 9 yamls are registered as parallel agent entry points
@@ -54,7 +54,7 @@ class CartpoleCameraShowcasePresetsEnvCfg(PresetCfg):
     """Camera-based cartpole showcase with selectable observation container and action space.
 
     Each variant attribute is an instance of an existing per-shape cfg class.
-    The hydra resolver picks one based on ``--presets=<name>``; the default
+    The hydra resolver picks one based on ``presets=<name>``; the default
     is ``box_box`` (matching the canonical cartpole camera shape).
     """
 
@@ -82,7 +82,7 @@ def _deprecated_factory(old_task_id: str, preset_name: str):
     retired showcase task ID. On invocation it emits a
     ``DeprecationWarning`` pointing at the consolidated
     ``Isaac-Cartpole-Camera-Showcase-Direct-v0`` task with the equivalent
-    ``--presets=<preset_name>``, then returns a fresh instance of the
+    ``presets=<preset_name>``, then returns a fresh instance of the
     corresponding per-shape cfg class.
 
     Args:
@@ -97,7 +97,7 @@ def factory():
         new_id = "Isaac-Cartpole-Camera-Showcase-Direct-v0"
         warnings.warn(
             f"Task '{old_task_id}' is deprecated and will be removed in a future release. "
-            f"Use --task={new_id} --presets={preset_name}.",
+            f"Use --task={new_id} presets={preset_name}.",
             DeprecationWarning,
             stacklevel=2,
         )

source/isaaclab_tasks/isaaclab_tasks/manager_based/classic/cartpole/cartpole_camera_presets_env_cfg.py

@@ -9,7 +9,7 @@
 :class:`CartpoleDepthCameraEnvCfg`, :class:`CartpoleResNet18CameraEnvCfg`,
 :class:`CartpoleTheiaTinyCameraEnvCfg`) in a single :class:`PresetCfg` so the
 ``Isaac-Cartpole-Camera-v0`` task can switch between them at runtime via
-``--presets=<name>`` (the typed preset CLI from #5587). Each retired task ID
+``presets=<name>`` (the typed preset CLI from #5587). Each retired task ID
 (``Isaac-Cartpole-{RGB,Depth,RGB-ResNet18,RGB-TheiaTiny}-v0``) routes its
 ``env_cfg_entry_point`` through one of the deprecation factories below.
 """
@@ -44,10 +44,10 @@ class CartpoleCameraPresetsEnvCfg(PresetCfg):
       backbone from the RGB camera.
 
     The variant attributes hold concrete env cfg instances, so the hydra
-    resolver picks one based on ``--presets=<name>`` (or the broadcast
-    ``--presets`` CSV) and the rest of the cfg tree is inherited from
-    :class:`CartpoleEnvCfg`, including the existing ``CartpolePhysicsCfg``
-    that powers the ``--physics`` typed flag.
+    resolver picks one based on ``presets=<name>`` (or the broadcast
+    ``presets=<name>,<name>,...`` CSV) and the rest of the cfg tree is
+    inherited from :class:`CartpoleEnvCfg`, including the existing
+    ``CartpolePhysicsCfg`` that powers the ``physics=`` typed selector.
     """
 
     default = CartpoleRGBCameraEnvCfg()
@@ -80,7 +80,7 @@ def _deprecated_factory(old_task_id: str, preset_name: str | None = None):
 
     def factory():
         new_id = "Isaac-Cartpole-Camera-v0"
-        tail = f"--task={new_id}" + (f" --presets={preset_name}" if preset_name else "")
+        tail = f"--task={new_id}" + (f" presets={preset_name}" if preset_name else "")
         warnings.warn(
             f"Task '{old_task_id}' is deprecated and will be removed in a future release. Use {tail}.",
             DeprecationWarning,

source/isaaclab_tasks/test/test_cartpole_preset_deprecations.py

@@ -11,7 +11,7 @@
 consolidated cfg. These tests lock that contract:
 
 * Every retired task ID emits a ``DeprecationWarning`` exactly once that
-  names the new consolidated task ID and the corresponding ``--presets`` name.
+  names the new consolidated task ID and the corresponding ``presets=`` name.
 * The new ``Isaac-Cartpole-Camera-Direct-v0`` and ``Isaac-Cartpole-Camera-v0``
   task IDs load cleanly with no deprecation warning of our own.
 
@@ -34,36 +34,36 @@
 # (deprecated task id, expected migration suffix appearing in the warning body)
 _DIRECT_DEPRECATIONS = [
     ("Isaac-Cartpole-Camera-Presets-Direct-v0", "--task=Isaac-Cartpole-Camera-Direct-v0"),
-    ("Isaac-Cartpole-RGB-Camera-Direct-v0", "--task=Isaac-Cartpole-Camera-Direct-v0 --presets=rgb"),
-    ("Isaac-Cartpole-Depth-Camera-Direct-v0", "--task=Isaac-Cartpole-Camera-Direct-v0 --presets=depth"),
-    ("Isaac-Cartpole-Albedo-Camera-Direct-v0", "--task=Isaac-Cartpole-Camera-Direct-v0 --presets=albedo"),
+    ("Isaac-Cartpole-RGB-Camera-Direct-v0", "--task=Isaac-Cartpole-Camera-Direct-v0 presets=rgb"),
+    ("Isaac-Cartpole-Depth-Camera-Direct-v0", "--task=Isaac-Cartpole-Camera-Direct-v0 presets=depth"),
+    ("Isaac-Cartpole-Albedo-Camera-Direct-v0", "--task=Isaac-Cartpole-Camera-Direct-v0 presets=albedo"),
     (
         "Isaac-Cartpole-SimpleShading-Constant-Camera-Direct-v0",
-        "--task=Isaac-Cartpole-Camera-Direct-v0 --presets=simple_shading_constant_diffuse",
+        "--task=Isaac-Cartpole-Camera-Direct-v0 presets=simple_shading_constant_diffuse",
     ),
     (
         "Isaac-Cartpole-SimpleShading-Diffuse-Camera-Direct-v0",
-        "--task=Isaac-Cartpole-Camera-Direct-v0 --presets=simple_shading_diffuse_mdl",
+        "--task=Isaac-Cartpole-Camera-Direct-v0 presets=simple_shading_diffuse_mdl",
     ),
     (
         "Isaac-Cartpole-SimpleShading-Full-Camera-Direct-v0",
-        "--task=Isaac-Cartpole-Camera-Direct-v0 --presets=simple_shading_full_mdl",
+        "--task=Isaac-Cartpole-Camera-Direct-v0 presets=simple_shading_full_mdl",
     ),
 ]
 
 _MANAGER_DEPRECATIONS = [
-    ("Isaac-Cartpole-RGB-v0", "--task=Isaac-Cartpole-Camera-v0 --presets=rgb"),
-    ("Isaac-Cartpole-Depth-v0", "--task=Isaac-Cartpole-Camera-v0 --presets=depth"),
-    ("Isaac-Cartpole-RGB-ResNet18-v0", "--task=Isaac-Cartpole-Camera-v0 --presets=resnet18"),
-    ("Isaac-Cartpole-RGB-TheiaTiny-v0", "--task=Isaac-Cartpole-Camera-v0 --presets=theia_tiny"),
+    ("Isaac-Cartpole-RGB-v0", "--task=Isaac-Cartpole-Camera-v0 presets=rgb"),
+    ("Isaac-Cartpole-Depth-v0", "--task=Isaac-Cartpole-Camera-v0 presets=depth"),
+    ("Isaac-Cartpole-RGB-ResNet18-v0", "--task=Isaac-Cartpole-Camera-v0 presets=resnet18"),
+    ("Isaac-Cartpole-RGB-TheiaTiny-v0", "--task=Isaac-Cartpole-Camera-v0 presets=theia_tiny"),
 ]
 
 # Proprioceptive cartpole showcase: 15 (observation, action) shape combinations
-# collapse into Isaac-Cartpole-Showcase-Direct-v0 via --presets=<obs>_<action>.
+# collapse into Isaac-Cartpole-Showcase-Direct-v0 via presets=<obs>_<action>.
 _PROPRIO_SHOWCASE_DEPRECATIONS = [
     (
         f"Isaac-Cartpole-Showcase-{obs_label}-{act_label}-Direct-v0",
-        f"--task=Isaac-Cartpole-Showcase-Direct-v0 --presets={obs}_{act}",
+        f"--task=Isaac-Cartpole-Showcase-Direct-v0 presets={obs}_{act}",
     )
     for obs_label, obs in [
         ("Box", "box"),
@@ -77,11 +77,11 @@
 
 # Camera-based cartpole showcase: 9 (observation, action) shape combinations
 # collapse into Isaac-Cartpole-Camera-Showcase-Direct-v0 via
-# --presets=<obs>_<action>.
+# presets=<obs>_<action>.
 _CAMERA_SHOWCASE_DEPRECATIONS = [
     (
         f"Isaac-Cartpole-Camera-Showcase-{obs_label}-{act_label}-Direct-v0",
-        f"--task=Isaac-Cartpole-Camera-Showcase-Direct-v0 --presets={obs}_{act}",
+        f"--task=Isaac-Cartpole-Camera-Showcase-Direct-v0 presets={obs}_{act}",
     )
     for obs_label, obs in [("Box", "box"), ("Dict", "dict"), ("Tuple", "tuple")]
     for act_label, act in [("Box", "box"), ("Discrete", "discrete"), ("MultiDiscrete", "multidiscrete")]
@@ -110,7 +110,7 @@ def _load_capturing_task_deprecations(task_id: str) -> list[str]:
 )
 def test_retired_task_id_emits_deprecation_pointing_at_new_task(task_id: str, migration: str) -> None:
     """Each retired cartpole perception task ID emits a DeprecationWarning
-    that names the consolidated task and the equivalent ``--presets`` value."""
+    that names the consolidated task and the equivalent ``presets=`` value."""
     messages = _load_capturing_task_deprecations(task_id)
     assert len(messages) == 1, f"{task_id}: expected 1 task-deprecation warning, got {len(messages)}: {messages}"
     body = messages[0]