Contribution Guidelines — Isaac Lab Documentation (original) (raw)

Contribution Guidelines#

We wholeheartedly welcome contributions to the project to make the framework more mature and useful for everyone. These may happen in forms of:

We prefer GitHub discussions for discussing ideas, asking questions, conversations and requests for new features.

Please use theissue tracker only to track executable pieces of work with a definite scope and a clear deliverable. These can be fixing bugs, new features, or general updates.

Contributing Code#

Attention

Please refer to the Google Style Guidefor the coding style before contributing to the codebase. In the coding style section, we outline the specific deviations from the style guide that we follow in the codebase.

We use GitHub for code hosting. Please follow the following steps to contribute code:

  1. Create an issue in the issue tracker to discuss the changes or additions you would like to make. This helps us to avoid duplicate work and to make sure that the changes are aligned with the roadmap of the project.
  2. Fork the repository.
  3. Create a new branch for your changes.
  4. Make your changes and commit them.
  5. Push your changes to your fork.
  6. Submit a pull request to the main branch.
  7. Ensure all the checks on the pull request template are performed.

After sending a pull request, the maintainers will review your code and provide feedback.

Please ensure that your code is well-formatted, documented and passes all the tests.

Tip

It is important to keep the pull request as small as possible. This makes it easier for the maintainers to review your code. If you are making multiple changes, please send multiple pull requests. Large pull requests are difficult to review and may take a long time to merge.

Contributing Documentation#

Contributing to the documentation is as easy as contributing to the codebase. All the source files for the documentation are located in the IsaacLab/docs directory. The documentation is written inreStructuredText format.

We use Sphinx with theBook Themefor maintaining the documentation.

Sending a pull request for the documentation is the same as sending a pull request for the codebase. Please follow the steps mentioned in the Contributing Code section.

To build the documentation, run the following command in the terminal which installs the required python packages and builds the documentation using the docs/Makefile:

./isaaclab.sh --docs # or "./isaaclab.sh -d"

The documentation is generated in the docs/_build directory. To view the documentation, open the index.html file in the html directory. This can be done by running the following command in the terminal:

xdg-open docs/_build/current/index.html

Hint

The xdg-open command is used to open the index.html file in the default browser. If you are using a different operating system, you can use the appropriate command to open the file in the browser.

To do a clean build, run the following command in the terminal:

rm -rf docs/_build && ./isaaclab.sh --docs

Contributing assets#

Currently, we host the assets for the extensions on NVIDIA Nucleus Server. Nucleus is a cloud-based storage service that allows users to store and share large files. It is integrated with the NVIDIA Omniverse Platform.

Since all assets are hosted on Nucleus, we do not need to include them in the repository. However, we need to include the links to the assets in the documentation.

The included assets are part of the Isaac Sim Content. To use this content, you can use the Asset Browser provided in Isaac Sim.

Please check the Isaac Sim documentationfor more information on how to download the assets.

Attention

We are currently working on a better way to contribute assets. We will update this section once we have a solution. In the meantime, please follow the steps mentioned below.

To host your own assets, the current solution is:

  1. Create a separate repository for the assets and add it over there
  2. Make sure the assets are licensed for use and distribution
  3. Include images of the assets in the README file of the repository
  4. Send a pull request with a link to the repository

We will then verify the assets, its licensing, and include the assets into the Nucleus server for hosting. In case you have any questions, please feel free to reach out to us through e-mail or by opening an issue in the repository.

Maintaining a changelog and extension.toml#

Each extension maintains a changelog in the CHANGELOG.rst file in the docs directory, as well as a extension.toml file in the config directory.

The extension.toml file contains the metadata for the extension. It is used to describe the name, version, description, and other metadata of the extension.

The CHANGELOG.rst is a file that contains the curated, chronologically ordered list of notable changes for each version of the extension.

Note

The version number on the extension.toml file should be updated according toSemantic Versioning and should match the version number in theCHANGELOG.rst file.

The changelog file is written in reStructuredText format. The goal of this changelog is to help users and contributors see precisely what notable changes have been made between each release (or version) of the extension. This is a MUST for every extension.

For updating the changelog, please follow the following guidelines:

Tip

When in doubt, please check the style in the existing changelog files and follow the same style.

For example, the following is a sample changelog:

Changelog

0.1.0 (2021-02-01)

~~~~~~~~~~~~~~~~~~

Added ^^^^^

Changed ^^^^^^^

Deprecated ^^^^^^^^^^

Removed ^^^^^^^

Fixed ^^^^^

Coding Style#

We follow the Google Style Guides for the codebase. For Python code, the PEP guidelines are followed. Most important ones are PEP-8for code comments and layout,PEP-484 andPEP-585 for type-hinting.

For documentation, we adopt the Google Style Guidefor docstrings. We use Sphinx for generating the documentation. Please make sure that your code is well-documented and follows the guidelines.

Circular Imports#

Circular imports happen when two modules import each other, which is a common issue in Python. You can prevent circular imports by adhering to the best practices outlined in thisStackOverflow post.

In general, it is essential to avoid circular imports as they can lead to unpredictable behavior.

However, in our codebase, we encounter circular imports at a sub-package level. This situation arises due to our specific code structure. We organize classes or functions and their corresponding configuration objects into separate files. This separation enhances code readability and maintainability. Nevertheless, it can result in circular imports because, in many configuration objects, we specify classes or functions as default values using the attributes class_type and func respectively.

To address circular imports, we leverage the typing.TYPE_CHECKING variable. This special variable is evaluated only during type-checking, allowing us to import classes or functions in the configuration objects without triggering circular imports.

It is important to note that this is the sole instance within our codebase where circular imports are used and are acceptable. In all other scenarios, we adhere to best practices and recommend that you do the same.

Type-hinting#

To make the code more readable, we use type hints for all the functions and classes. This helps in understanding the code and makes it easier to maintain. Following this practice also helps in catching bugs early with static type checkers like mypy.

Type-hinting only in the function signature

To avoid duplication of efforts, we do not specify type hints for the arguments and return values in the docstrings.

For instance, the following are bad examples for various reasons:

def my_function(a, b): """Adds two numbers.

This function is a bad example. Reason: No type hints anywhere.

Args: a: The first argument. b: The second argument.

Returns: The sum of the two arguments. """ return a + b

def my_function(a, b): """Adds two numbers.

This function is a bad example. Reason: Type hints in the docstring and not in the function signature.

Args: a (int): The first argument. b (int): The second argument.

Returns: int: The sum of the two arguments. """ return a + b

def my_function(a: int, b: int) -> int: """Adds two numbers.

This function is a bad example. Reason: Type hints in the docstring and in the function signature. Redundancy.

Args: a (int): The first argument. b (int): The second argument.

Returns: int: The sum of the two arguments. """ return a + b

The following is how we expect you to write the docstrings and type hints:

def my_function(a: int, b: int) -> int: """Adds two numbers.

This function is a good example. Reason: Type hints in the function signature and not in the docstring.

Args: a: The first argument. b: The second argument.

Returns: The sum of the two arguments. """ return a + b

No type-hinting for None

We do not specify the return type of None in the docstrings. This is because it is not necessary and can be inferred from the function signature.

For instance, the following is a bad example:

def my_function(x: int | None) -> None: pass

Instead, we recommend the following:

def my_function(x: int | None): pass

Documenting the code#

The code documentation is as important as the code itself. It helps in understanding the code and makes it easier to maintain. However, more often than not, the documentation is an afterthought or gets rushed to keep up with the development pace.

What is considered as a bad documentation?

What is considered good documentation?

We recommend thinking of the code documentation as a living document that helps the reader understand the what, why and how of the code. Often we see documentation that only explains the what but not the how or why. This is not helpful in the long run.

We suggest always thinking of the documentation from a new user’s perspective. They should be able to directly check the documentation and have a good understanding of the code.

For information on how to write good documentation, please check the notes onDart’s effective documentationand technical writing. We summarize the key points below:

Unit Testing#

We use unittest for unit testing. Good tests not only cover the basic functionality of the code but also the edge cases. They should be able to catch regressions and ensure that the code is working as expected. Please make sure that you add tests for your changes.

Tools#

We use the following tools for maintaining code quality:

Please check here for instructions to set these up. To run over the entire repository, please execute the following command in the terminal:

./isaaclab.sh --format # or "./isaaclab.sh -f"