Contributing to IR-SIM#

Thank you for your interest in improving IR-SIM! Whether you’re fixing a typo, adding a new feature, or writing documentation, your contribution is welcome by opening an issue or a pull request to the main branch. Below are a few guidelines to help you get started.

New here? Browse issues labelled good first issue for a friendly starting point. By participating, you agree to uphold our Code of Conduct.

What You Can Contribute#

  • Source Code

    • New features (sensors, controllers, kinematic models)

    • Bug fixes and performance improvements

  • Documentation

    • Fix typos, clarify API descriptions

    • Add new tutorials or usage guides

    • Improve examples under docs/

  • Usage Examples & Tests

    • Extend or polish the usage/ directory

    • Add unit tests for new features

  • Discussion & Design

    • Propose architectural changes

    • Provide feedback on roadmap or UX

Code Style#

We use Ruff to format and lint Python code. Before opening a PR, run:

pip install ruff
ruff check

To enable automatic checks on each commit, install the pre-commit hook:

pip install pre-commit
pre-commit install

Documentation#

IR-SIM’s documentation lives in the docs/ directory and uses the PyData Sphinx Theme. To build the docs locally:

cd docs
make html

  • New tutorials or guides belong in docs/ or under usage/

  • The API reference is auto-generated from docstrings

Adding New Features#

Current support of sensors, behaviors, and robot kinematics models can be seen in the support.

New features to support more platforms and scenarios to make IR-SIM more versatile are welcome. Please open an issue to discuss the design. If you prefer, you can also email hanrh@connect.hku.hk for a design discussion.

Testing#

We use pytest for our test suite. To run all tests:

pytest

Please add tests for any new functionality or bug fix.

Pull Requests#

Open pull requests against the main branch, and keep each PR focused on a single change. Before submitting, run ruff check and pytest.

Use a Conventional Commits-style title — <type>(<scope>): <subject> — where <type> is one of feat, fix, docs, style, refactor, test, or chore (the scope is optional):

feat: add hat wobble
fix(lidar): correct beam angle wrapping
docs: clarify behavior registration

Thanks again for helping make IR-SIM better!