CONTRIBUTING.md

Contributing to MuJoCo Toolbox

Thank you for your interest in contributing!
This guide outlines how to set up your development environment, follow project conventions, and submit high-quality contributions to the project.

📚 Table of Contents

• Contributing to MuJoCo Toolbox
  • 📚 Table of Contents
  • 📜 Code of Conduct
  • ⚙️ Getting Started
  • 🚀 How to Contribute
  • 🧑‍💻 Development Guidelines
  • 🔍 Linting and Automation
  • 📖 Building the Documentation Locally
  • 🐞 Reporting Issues
  • 📄 License

---

📜 Code of Conduct

Please review the Code of Conduct to ensure a respectful and productive environment for all contributors.

---

⚙️ Getting Started

1. Fork and clone the repository:

   git clone https://github.com/MGross21/mujoco-toolbox.git
   cd mujoco-toolbox

2. Install Poetry (if you haven’t already):

   curl -sSL https://install.python-poetry.org | python3 -

   Or see: Poetry Installation Docs

3. Install dependencies:

   poetry install --with dev

4. Activate the shell:

   poetry shell

   or

   poetry env activate

---

🚀 How to Contribute

We welcome:

• 🐛 Bug fixes
• 📚 Documentation improvements
• 🚀 New features
• 🧪 Additional tests
• 🔧 Code refactors

For significant changes, please open an issue or start a discussion first.

---

🧑‍💻 Development Guidelines

• Write clean, modular, and well-documented code.
• Use meaningful names for variables, classes, and functions.
• Avoid large, complex functions — break logic into smaller components.
• Public classes and functions must include Python docstrings.
• Avoid unnecessary dependencies.
• Add or update tests for any new features or bug fixes.

---

🔍 Linting and Automation

All pull requests are automatically checked using GitHub Actions.

The following tools are enforced:

• black – formatting
• ruff – linting
• mypy – type checking
• pytest – test runner

⚠️ Your pull request must pass all checks before it can be merged.

Run checks locally using Poetry:

poetry run black mujoco_toolbox
poetry run ruff check mujoco_toolbox
poetry run mypy mujoco_toolbox
poetry run pytest tests/

📖 Building the Documentation Locally

To build the documentation locally, run:

poetry run sphinx-build docs docs/_build/html

To automatically open the generated documentation in your default web browser after building, use:

poetry run sphinx-build docs docs/_build/html && start docs/_build/html/index.html

This will generate the HTML documentation and open the index.html page for easy viewing.

🐞 Reporting Issues

Use GitHub Issues to:

• Report bugs
• Request features
• Ask usage questions
• Suggest improvements

Please include:

• A clear and descriptive title
• Environment information (OS, Python version, MuJoCo Toolbox version, etc.)
• Reproduction steps (if applicable)
• Screenshots or logs (when helpful)

---

📄 License

By contributing, you agree that your work will be released under the MIT License.