Skip to content

Latest commit

 

History

History
77 lines (58 loc) · 3.16 KB

CONTRIBUTING.md

File metadata and controls

77 lines (58 loc) · 3.16 KB
Raw

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)
  • Add an entirely new model

Note that Menagerie follows Google's Open Source Community Guidelines.

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. 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 (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 using the XML Language Support by Red Hat 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:

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.