109 lines
2.7 KiB
ReStructuredText
109 lines
2.7 KiB
ReStructuredText
|
Contributing
|
||
|
|
============
|
||
|
|
|
||
|
|
Bug fixes and documentation improvements are always welcome.
|
||
|
|
|
||
|
|
.. important::
|
||
|
|
|
||
|
|
For new features, please
|
||
|
|
`open an issue <https://github.com/mujocolab/mjlab/issues>`_ first so
|
||
|
|
we can discuss whether it fits the project scope.
|
||
|
|
|
||
|
|
|
||
|
|
Development setup
|
||
|
|
-----------------
|
||
|
|
|
||
|
|
Clone the repository and sync dependencies:
|
||
|
|
|
||
|
|
.. code-block:: bash
|
||
|
|
|
||
|
|
git clone https://github.com/mujocolab/mjlab.git && cd mjlab
|
||
|
|
uv sync
|
||
|
|
|
||
|
|
Install pre-commit hooks to catch formatting and lint issues before each
|
||
|
|
commit:
|
||
|
|
|
||
|
|
.. code-block:: bash
|
||
|
|
|
||
|
|
uvx pre-commit install
|
||
|
|
|
||
|
|
|
||
|
|
Common commands
|
||
|
|
---------------
|
||
|
|
|
||
|
|
The ``Makefile`` provides shortcuts for the most common development tasks:
|
||
|
|
|
||
|
|
.. code-block:: bash
|
||
|
|
|
||
|
|
make format # Format code and fix lint errors (ruff)
|
||
|
|
make type # Type check (ty + pyright)
|
||
|
|
make check # Format + type check
|
||
|
|
make test-fast # Run tests, excluding slow ones
|
||
|
|
make test # Run the full test suite
|
||
|
|
make test-all # Format + type check + full test suite
|
||
|
|
|
||
|
|
You can also run individual tests for faster iteration:
|
||
|
|
|
||
|
|
.. code-block:: bash
|
||
|
|
|
||
|
|
uv run pytest tests/test_rewards.py
|
||
|
|
|
||
|
|
Type checking (``make type``) is required. PRs that do not pass will be
|
||
|
|
blocked.
|
||
|
|
|
||
|
|
|
||
|
|
Building the docs
|
||
|
|
-----------------
|
||
|
|
|
||
|
|
Build the documentation locally:
|
||
|
|
|
||
|
|
.. code-block:: bash
|
||
|
|
|
||
|
|
make docs
|
||
|
|
|
||
|
|
The HTML output is written to ``docs/_build/``. For live reload during
|
||
|
|
editing:
|
||
|
|
|
||
|
|
.. code-block:: bash
|
||
|
|
|
||
|
|
make docs-watch
|
||
|
|
|
||
|
|
|
||
|
|
Submitting a pull request
|
||
|
|
-------------------------
|
||
|
|
|
||
|
|
1. Fork the repository and create a feature branch.
|
||
|
|
2. Make your changes.
|
||
|
|
3. Run ``make test-all`` to verify formatting, type checking, and tests
|
||
|
|
pass.
|
||
|
|
4. Add an entry to the "Upcoming version" section in
|
||
|
|
``docs/source/changelog.rst`` under the appropriate category
|
||
|
|
(Added / Changed / Fixed), following
|
||
|
|
`Keep a Changelog <https://keepachangelog.com/>`_ conventions.
|
||
|
|
5. Submit a pull request.
|
||
|
|
|
||
|
|
|
||
|
|
Development with Claude Code
|
||
|
|
----------------------------
|
||
|
|
|
||
|
|
The repository includes a ``CLAUDE.md`` file at the project root. This file
|
||
|
|
defines development conventions, style guidelines, and common commands for
|
||
|
|
`Claude Code <https://claude.com/claude-code>`_. It is also a useful
|
||
|
|
reference for human contributors since it captures the same rules enforced
|
||
|
|
in CI.
|
||
|
|
|
||
|
|
The project also includes shared commands in ``.claude/commands/``.
|
||
|
|
Any contributor with Claude Code installed can invoke them as slash commands.
|
||
|
|
|
||
|
|
``/update-mjwarp <commit-hash>``
|
||
|
|
Update the ``mujoco-warp`` dependency to a specific commit. This edits
|
||
|
|
``pyproject.toml``, runs ``uv lock``, and opens a PR in one step.
|
||
|
|
|
||
|
|
.. code-block:: text
|
||
|
|
|
||
|
|
/update-mjwarp e28c6038cdf8a353b4146974e4cf37e74dda809a
|
||
|
|
|
||
|
|
``/commit-push-pr``
|
||
|
|
Stage current changes, commit, push, and open a PR.
|
||
|
|
|