78 lines
3.2 KiB
Markdown
78 lines
3.2 KiB
Markdown
# Contributing to Menagerie
|
||
|
||
We want Menagerie to be a true community-driven effort that continuously
|
||
improves and grows over time for the benefit of the entire research community.
|
||
As such, we welcome contributions that:
|
||
|
||
- Fix issues with an existing model
|
||
- Improve the realism of a model (e.g. via
|
||
[system identification](https://en.wikipedia.org/wiki/System_identification))
|
||
- Add an entirely new model
|
||
|
||
Note that Menagerie follows [Google's Open Source Community Guidelines](https://opensource.google/conduct/).
|
||
|
||
## How to contribute
|
||
|
||
Whether you want to fix an issue with an existing model, improve it, or add a
|
||
completely new model, please get in touch with us first (ideally _before_
|
||
starting work if it's something major) by opening a new
|
||
[issue](https://github.com/google-deepmind/mujoco_menagerie/issues).
|
||
Coordinating up front makes it much easier to avoid frustration later on.
|
||
|
||
Once we reach an agreement on the proposed change, please submit a
|
||
[pull request](https://github.com/google-deepmind/mujoco_menagerie/pulls) (PR)
|
||
so that we can review your implementation.
|
||
|
||
## XML Style
|
||
|
||
You can browse existing models to get a general sense of the style we adopt for
|
||
our MJCF (XML) files. In no particular order, we try to adhere to the following
|
||
guidelines:
|
||
|
||
- Use 2-space indentation
|
||
- Make generous use of default classes to reduce redundancies in the kinematic
|
||
tree
|
||
- Preserve attribute ordering: compiler, asset and default class definitions
|
||
first, then worldbody and actuators, etc.
|
||
- Always have a `scene.xml` that includes the model
|
||
|
||
Furthermore, we automatically format our XMLs in [Visual Studio Code](https://code.visualstudio.com/)
|
||
using the [XML Language Support by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-xml)
|
||
extension. Once installed, you will need to edit its settings as follows:
|
||
|
||
- View > Command Palette > `Preferences: Open User Settings`
|
||
- Search for XML
|
||
- `Enforce quote style` → preferred
|
||
- `Max line width` → 120
|
||
- `Preserve attribute line breaks` → toggle OFF
|
||
- `Xml › Format: Space Before Empty Close Tag` → toggle OFF
|
||
|
||
Once installed, you can format an XML file by opening the command palette and
|
||
executing `Format Document`.
|
||
|
||
## Unit Tests
|
||
|
||
Before submitting your PR, you can test your change locally by invoking pytest:
|
||
|
||
```bash
|
||
pytest test/
|
||
```
|
||
|
||
This same test will run on GitHub CI once you open your PR. Currently,
|
||
`model_test.py` simply simulates each robot for a fixed duration of time and
|
||
checks that no simulation instabilities occur. In the future, we will likely add
|
||
more tests that check for model realism (e.g., that a trajectory in real matches
|
||
one in simulation).
|
||
|
||
## Contributor License Agreement
|
||
|
||
Contributions to this project must be accompanied by a Contributor License
|
||
Agreement (CLA). You (or your employer) retain the copyright to your
|
||
contribution; this simply gives us permission to use and redistribute your
|
||
contributions as part of the project. Head over to <https://cla.developers.google.com/>
|
||
to see your current agreements on file or to sign a new one.
|
||
|
||
You generally only need to submit a CLA once, so if you've already submitted one
|
||
(even if it was for a different project), you probably don't need to do it
|
||
again.
|