Contributing

The framework is split across six repositories. Three are public and accept contributions; one (this docs hub) is also public; two host application code that lives alongside the framework.

Repositories

Repository

Role

https://github.com/ncbdrck/UniROS

Canonical home for the gym-proxy class and shared ROS utilities. Bug fixes here flow to multiros and realros via re-exports. Also hosts this documentation site.

https://github.com/ncbdrck/multiros

Gazebo simulation layer.

https://github.com/ncbdrck/realros

Real-hardware layer.

https://github.com/ncbdrck/sb3_ros_support

Stable Baselines 3 wrappers.

https://github.com/ncbdrck/rl_environments

Ready-made gymnasium environments (RX200, NED2, …).

https://github.com/ncbdrck/rl_training_validation

Training scripts that exercise the rl_environments envs.

Development setup

Set up a Noetic catkin workspace as in Installation, then check out the development branches you want to work on. Active work usually happens on a feature or integration branch before merging to the repo’s default branch (gymnasium for the four framework repos, main for the application repos).

Run the test suites before committing — see Testing.

For docs work specifically:

cd ~/catkin_ws/src/UniROS
pip install -r docs/requirements.txt
sphinx-build -b html docs docs/_build/html

Open docs/_build/html/index.html in a browser to preview.

Before pushing docs changes, run the Python-code-block syntax check that CI runs:

python scripts/check_python_code_blocks.py docs -v

It compiles every .. code-block:: python snippet under docs/. SyntaxError here usually means a trailing ... inside a function call, a missing closing bracket, or a pseudo-code snippet that should have been tagged .. code-block:: text (or any non-python lexer) rather than python.

Commit conventions

  • Use focused commits, one logical change each.

  • Lead with an imperative summary line under 72 characters.

  • Body should explain the why, not the what — the diff already shows the what.

  • Reference the affected package in the summary when it isn’t obvious from the file paths.

Pull requests

  • Open against the relevant repo’s default branch.

  • Include a one-paragraph context block (what changed, why, how to verify) in the PR description.

  • If you’ve added or changed a public API, update the matching page under docs/api/ and confirm the local Sphinx build succeeds.

  • CI is green is a prerequisite; the workflow takes ~30 seconds per Python version once the cache is warm.