[Proposal] Stable `main` Branch Structure and Specific Versioning in Installation Guides

[d-kleine]

Proposal

To improve clarity and prevent version mismatches between IsaacLab and Isaac Sim, I would like to suggest following changes:

• Align the main branch of the IsaacLab repository with the latest stable release to ensure alignment with the current stable Isaac Sim release (developer releases should instead be maintained in a separate branch)

• Update the installation documentation to explicitly reference versioned releases and compatibility requirements by improving cloning instructions by requiring users to explicitly check out a tagged stable release rather than implicitly using git clone https://github.com/isaac-sim/IsaacLab.git, for example

  git clone https://github.com/isaac-sim/IsaacLab.git --branch v2.3.2 

  respectively

  pip install isaaclab==2.3.2

Motivation

The current installation guide assumes cloning the repo using git clone https://github.com/isaac-sim/IsaacLab.git, but main is already ahead of the latest stable release and aligned with the upcoming Isaac Lab v3 beta (that requires Isaac Sim 6 + Python 3.12). For example, see here:
https://isaac-sim.github.io/IsaacLab/v2.3.2/source/setup/installation/pip_installation.html#cloning-isaac-lab
https://isaac-sim.github.io/IsaacLab/v2.3.2/source/setup/installation/binaries_installation.html#cloning-isaac-lab
https://isaac-sim.github.io/IsaacLab/v2.3.2/source/setup/installation/source_installation.html#cloning-isaac-lab

This creates a mismatch for users who expect main to reflect the stable version (currently Isaac Lab 2.3.2 for Isaac Sim 5.1 + Python 3.11). As a result, users following the default instructions may unintentionally install or build against an incompatible development version, leading to breakages or confusion.

Providing explicit version pinning (both in pip and git workflows) in the installation guidelines (pip, pre-built binaries, source build) would reduce compatibility issues, particularly for users targeting the current stable Isaac Sim 5.1 ecosystem.

Build Info

• Isaac Lab Version: 2.3.2
• Isaac Sim Version: 5.1.0

Checklist

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

[9514]

it occured the same question there during installing
File "C:\Users\Mengyuan\AppData\Local\Temp\pip-build-env-372nk5tl\overlay\Lib\site-packages\setuptools\build_meta.py", line 333, in get_requires_for_build_wheel
return self._get_build_requires(config_settings, requirements=[])
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "C:\Users\Mengyuan\AppData\Local\Temp\pip-build-env-372nk5tl\overlay\Lib\site-packages\setuptools\build_meta.py", line 301, in _get_build_requires
self.run_setup()
File "C:\Users\Mengyuan\AppData\Local\Temp\pip-build-env-372nk5tl\overlay\Lib\site-packages\setuptools\build_meta.py", line 520, in run_setup
super().run_setup(setup_script=setup_script)
File "C:\Users\Mengyuan\AppData\Local\Temp\pip-build-env-372nk5tl\overlay\Lib\site-packages\setuptools\build_meta.py", line 317, in run_setup
exec(code, locals())
File "", line 1, in
ModuleNotFoundError: No module named 'pkg_resources'
[end of output]

note: This error originates from a subprocess, and is likely not a problem with pip.
ERROR: Failed to build 'flatdict' when getting requirements to build wheel