Skip to content

[Docs] DOC-007: Migration guide: per-section review owners and checks #8389

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’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kellyguo11 merged 3 commits into from
Oct 10, 2026
Merged

[Docs] DOC-007: Migration guide: per-section review owners and checks #8389

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1357af9
Fix stale API claims in the 3.0 migration guide
AntoineRichard Oct 8, 2026
70a586c
Fix MJCF collision_type example values in the 3.0 migration guide
AntoineRichard Oct 8, 2026
3fa6f25
Fix keyword-only write call and convert_quat note in the 3.0 migratio…
AntoineRichard Oct 8, 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
31 changes: 16 additions & 15 deletions docs/source/migration/migrating_to_isaaclab_3-0.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1031,7 +1031,7 @@ removed in a future release.

Actuator configurations now use joint-qualified names for solver limits. Update active
configurations to the canonical fields below. The former names remain accepted with a
``DeprecationWarning`` through the 3.x release line and will be removed in 3.1.
``DeprecationWarning`` and will be removed in 3.1.

.. list-table:: Actuator limit migration
:header-rows: 1
Expand All @@ -1053,7 +1053,7 @@ configurations to the canonical fields below. The former names remain accepted w
``actuator_effort_limit`` clips explicit actuator-model output. ``joint_effort_limit`` and
``joint_velocity_limit`` are construction-time joint-property overrides selected by an actuator
group's joint expression. The deprecated aliases ``effort_limit``, ``velocity_limit``,
``effort_limit_sim``, and ``velocity_limit_sim`` remain accepted through 3.x. ``effort_limit``
``effort_limit_sim``, and ``velocity_limit_sim`` remain accepted until 3.1. ``effort_limit``
resolves to the rated ``actuator_effort_limit`` for every actuator type. For an implicit group
without a separately configured solver clamp, the rated value also populates
``joint_effort_limit`` for backward compatibility; configure both fields to author distinct
Expand Down Expand Up @@ -1678,7 +1678,7 @@ pattern as the general ProxyArray backend migration described above.
**Ray Alignment Configuration**

The ``attach_yaw_only`` boolean parameter on :class:`~isaaclab.sensors.RayCasterCfg` has been
deprecated in favor of the new ``ray_alignment`` parameter, which accepts one of three string
removed in favor of the new ``ray_alignment`` parameter, which accepts one of three string
values:

.. list-table::
Expand Down Expand Up @@ -1786,7 +1786,7 @@ Migrate tensor access, indexed writes, buffers, and quaternion conventions befor

identity = (0.0, 0.0, 0.0, 1.0)
root_pos = robot.data.root_pos_w.torch
robot.write_root_pose_to_sim_index(pose, env_ids)
robot.write_root_pose_to_sim_index(root_pose=pose, env_ids=env_ids)


.. rubric:: Quaternion Format
Expand Down Expand Up @@ -2049,18 +2049,19 @@ by the convention change.

.. rubric:: Quaternion Utility API Changes

**The ``convert_quat`` function has been removed**
**The convert_quat function is no longer needed**

Previously, IsaacLab had a utility function to convert between quaternion formats:
IsaacLab provides a utility function to convert between quaternion formats:

@isaaclab-review-bot isaaclab-review-bot Bot Oct 9, 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.

🟡 Warning · Style Consistency — convert_quat guidance contradicts its example

The new text says Isaac Lab provides convert_quat and to keep it for external WXYZ data, but the snippet it introduces is still labeled # OLD - No longer needed and the next sentence says…


.. code-block:: python

# OLD - No longer needed
from isaaclab.utils.math import convert_quat
quat_xyzw = convert_quat(quat_wxyz, "xyzw")

Since everything now uses XYZW natively, this function is no longer needed.
If you were using it, simply remove the conversion calls.
Since everything now uses XYZW natively, this function is no longer needed for Isaac Lab data.
If you were using it, simply remove the conversion calls. Keep it only to convert external
data that still uses WXYZ order.
Comment on lines +2062 to +2064

@greptile-apps greptile-apps Bot Oct 9, 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.

P2 Some conversions are still needed

The corrected paragraph still tells readers to remove conversions for all Isaac Lab data. Older Isaac Lab datasets use WXYZ, and generate_data.py still converts their action quaternions before replay. convert_quat also converts current XYZW data to WXYZ for external policies.

Limit the removal advice to conversions around current native XYZW data. Keep conversions for older datasets and external policies; removing them can silently produce wrong rotations.

Suggested change
Since everything now uses XYZW natively, this function is no longer needed for Isaac Lab data.
If you were using it, simply remove the conversion calls. Keep it only to convert external
data that still uses WXYZ order.
Current Isaac Lab APIs use XYZW natively, so remove conversions that only adapted native
Isaac Lab data to the old WXYZ convention. Keep conversions when reading older WXYZ datasets
or exchanging data with external tools and policies that use WXYZ.

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!



**Math utility functions now expect XYZW**
Expand Down Expand Up @@ -2251,7 +2252,8 @@ All asset write methods have been split into two explicit variants:
boolean mask selecting which environments to update. The ``data`` tensor has shape
``(num_envs, ...)``.

The previous ``write_*_to_sim(data, env_ids)`` methods have been removed.
The previous ``write_*_to_sim(data, env_ids)`` methods are deprecated and forward to the
``_index`` variants.

.. code-block:: python

Expand Down Expand Up @@ -2938,8 +2940,6 @@ and ``MJCFImporterConfig`` dataclass.
The following :class:`~sim.converters.MjcfConverterCfg` settings have been **removed** because
the new converter handles them automatically based on the MJCF file content:

- ``fix_base`` — base fixedness is now inferred from the MJCF ``<freejoint>`` tag.
- ``link_density`` — density is now read directly from the MJCF model.
- ``import_inertia_tensor`` — inertia tensors are always imported.
- ``import_sites`` — sites are always imported.

Expand All @@ -2958,8 +2958,8 @@ The following new settings were added to :class:`~sim.converters.MjcfConverterCf
+-----------------------------------------------------------------+------------------------------------------------------+
| :attr:`~sim.converters.MjcfConverterCfg.collision_from_visuals` | Generate collision geometry from visuals. |
+-----------------------------------------------------------------+------------------------------------------------------+
| :attr:`~sim.converters.MjcfConverterCfg.collision_type` | Type of collision geometry (e.g. ``"default"``, |
| | ``"Convex Hull"``, ``"Convex Decomposition"``). |
| :attr:`~sim.converters.MjcfConverterCfg.collision_type` | Type of collision geometry (e.g. ``"Convex Hull"``, |
| | ``"Convex Decomposition"``, ``"Bounding Cube"``). |
+-----------------------------------------------------------------+------------------------------------------------------+


Expand Down Expand Up @@ -3225,11 +3225,12 @@ For full documentation on the new stack, see :ref:`isaac-teleop-feature`.

**Installation Requirement**

Isaac Capture must now be installed in your Isaac Lab environment:
Isaac Capture must now be installed in your Isaac Lab environment. It ships with the ``teleop``
extra:

.. code-block:: bash

pip install isaacteleop~=1.0 --extra-index-url https://pypi.nvidia.com
uv sync --extra teleop --extra isaacsim

@greptile-apps greptile-apps Bot Oct 9, 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.

P2 Installing teleoperation removes other extras

Unlike the old additive install command, uv sync --extra teleop --extra isaacsim removes packages from other extras the user previously selected. Someone adding teleoperation to an environment with sb3 or rl-games can lose those integrations and break their training workflows.

Add a note to repeat existing compatible extras, as the installation guide already requires.

Suggested change
uv sync --extra teleop --extra isaacsim
uv sync --extra teleop --extra isaacsim
Repeat any existing compatible ``--extra`` selections in this command; otherwise,
``uv sync`` removes packages belonging to extras you omit.


See :ref:`install-isaac-teleop` for complete installation instructions.

Expand Down
Loading