[Proposal] Unify how warnings are emitted across Isaac Lab #8192

Proposal

Adopt one documented convention for emitting warnings across Isaac Lab, add it to the contribution guide's coding style, and migrate existing call sites to it.

A possible convention, following the standard library's own guidance (logging HOWTO: when to use logging):

Motivation

Develop (9c572e4) currently uses three mechanisms for the same purpose, excluding tests:

Most warnings.warn calls (306) are deprecations, which is consistent. The rest is not:

• The same kind of event uses different mechanisms.

  • isaaclab_physx/sensors/contact_sensor/contact_sensor.py:688 reports a visualization limitation with warnings.warn (no category) and a hand-rolled _warned_* flag to avoid repeats.
  • The same file (:483) and the other PhysX sensors report their CUDA-graph fallback with logger.warning.

• print warnings bypass logging. Examples:

  • isaaclab_rl/rsl_rl/utils.py (5 calls)
  • isaaclab/cli/multigpu.py
  • isaaclab/benchmark/.../benchmark_train_rl_games.py
  • scripts/reinforcement_learning/ray/*

  These ignore log levels and --verbose / --info, can't be filtered or captured with caplog, and use inconsistent prefixes ([WARNING]:, [WARNING], [WARN], [WARN]:).

• Tests can't assert warnings uniformly. Some need pytest.warns, some caplog, some capsys.

• New code has no reference to follow. This came up while reviewing a device fallback in [Mac OS] [RL] Run RL agents on the simulation device and raise without CUDA #8188.

Alternatives

• Only warnings.warn. This routes everything through the warnings filter. Runtime notices would then show once per call site by default, which suits deprecations but hides repeated runtime events. It also loses log levels and handlers.
• Only logging. Deprecations would lose DeprecationWarning semantics: they couldn't be turned into errors with -W error / pytest filterwarnings, and they'd have no stacklevel attribution to the caller.
• Status quo, documented. This lowers churn but keeps three idioms.

Build Info

• Isaac Lab Version: develop @ 9c572e4
• Isaac Sim Version: n/a (code-style proposal)

Checklist

• I have checked that there is no similar issue in the repo (required)

Acceptance Criteria

• The convention is documented in docs/source/refs/contributing.rst (Coding Style).
• print-based warnings in source/ and scripts/ are migrated to logger.warning (or warnings.warn where the caller must act).
• Non-deprecation warnings.warn calls are reviewed and either given an explicit category or moved to logger.warning per the convention.
• Optional: a lint check (e.g. a pre-commit grep or ruff rule) rejects new print("[WARN calls in source/.