> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/NVIDIA/Isaac-GR00T/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

> How to contribute to the Isaac GR00T project

Thanks for considering contributing to NVIDIA Isaac GR00T! This guide explains the various ways you can contribute to this project and how to get started.

## Bug reports and feature requests

### Reporting bugs

Before creating a bug report:

1. **Search existing issues**: Do a [quick search](https://github.com/NVIDIA/Isaac-GR00T/issues) to see if your issue has already been reported
2. **Comment on existing issues**: If your issue exists, add any additional information as a comment

If you've confirmed it's a new issue:

1. [Open a new GitHub issue](https://github.com/NVIDIA/Isaac-GR00T/issues/new)
2. Include a clear title and description
3. Provide:
   * Steps to reproduce the error
   * Expected behavior vs actual behavior
   * Code samples or test cases demonstrating the issue
   * Error messages and stack traces
   * Environment details (CUDA version, GPU model, OS, etc.)

<Tip>
  The more information you provide, the easier it is for maintainers to reproduce and fix the issue.
</Tip>

### Suggesting features

Before creating a feature request:

1. **Clarify your idea**: Make sure you have a clear vision of the enhancement
2. **Check documentation**: Verify the feature doesn't already exist
3. **Search existing issues**: Do a [quick search](https://github.com/NVIDIA/Isaac-GR00T/issues) to avoid duplicates

When creating your feature request:

1. **Provide a clear title and description**
2. **Explain the use case**: Why would this enhancement be useful?
3. **Show examples**: Highlight similar features in other libraries if applicable
4. **Include code examples**: Demonstrate how the feature would be used

## Making a pull request

Follow these guidelines when contributing code to help us review your pull request quickly.

### Initial setup (one-time)

<Steps>
  <Step title="Fork the repository">
    [Fork](https://help.github.com/en/enterprise/2.13/user/articles/fork-a-repo) the Isaac GR00T repository on GitHub.
  </Step>

  <Step title="Clone your fork">
    Clone your fork locally:

    ```bash theme={null}
    git clone https://github.com/USERNAME/Isaac-GR00T.git
    # or
    git clone git@github.com:USERNAME/Isaac-GR00T.git
    ```
  </Step>

  <Step title="Add upstream remote">
    Add the main repository as an upstream remote:

    ```bash theme={null}
    git remote add upstream https://github.com/NVIDIA/Isaac-GR00T.git
    ```

    Verify your remotes:

    ```bash theme={null}
    git remote -v
    ```

    You should see:

    ```
    origin    https://github.com/USERNAME/Isaac-GR00T.git (fetch)
    origin    https://github.com/USERNAME/Isaac-GR00T.git (push)
    upstream  https://github.com/NVIDIA/Isaac-GR00T.git (fetch)
    upstream  https://github.com/NVIDIA/Isaac-GR00T.git (push)
    ```
  </Step>

  <Step title="Install in editable mode">
    Create a development environment and install GR00T in editable mode:

    ```bash theme={null}
    uv pip install -e .[dev]
    ```

    The `-e` flag creates a symbolic link from your virtual environment to your local source code, so changes are immediately reflected.
  </Step>
</Steps>

### Keeping your fork up-to-date

Once you've added an upstream remote, keeping your fork synchronized is easy:

```bash theme={null}
git checkout main  # if not already on main
git pull --rebase upstream main
git push
```

### Creating a branch for your changes

<Warning>
  Committing directly to the main branch of your fork is not recommended. Working on a separate branch for each contribution keeps your fork cleaner.
</Warning>

Create a new branch:

```bash theme={null}
# Replace BRANCH with a descriptive name
git checkout -b BRANCH
git push -u origin BRANCH
```

### Testing your changes

Before opening a pull request, run the following checks locally to speed up the review process.

#### Code formatting and linting

GR00T uses [`ruff`](https://docs.astral.sh/ruff/) for code formatting and linting.

<Tip>
  Many IDEs support ruff as a plugin, allowing automatic formatting on save. For example, [black.vim](https://github.com/psf/black/tree/master/plugin) provides this functionality in Vim.
</Tip>

Run ruff from the command line:

```bash theme={null}
# Format code
ruff format .

# Fix linting issues automatically
ruff check --fix .
```

#### Running tests

We strive to maintain high test coverage. Most contributions should include additions to the unit tests.

Run tests with [`pytest`](https://docs.pytest.org/en/latest/):

```bash theme={null}
# Run all tests
pytest -v

# Run specific test module
pytest -v tests/gr00t/data/test_embodiment.py

# Run tests for a specific function you modified
pytest -v tests/gr00t/policy/test_policy.py::test_get_action
```

**Example**: If you've fixed a bug in `gr00t/policy/policy.py`, run:

```bash theme={null}
pytest -v tests/gr00t/policy/test_policy.py
```

### Opening a pull request

After all checks have passed:

1. Open [a new GitHub pull request](https://github.com/NVIDIA/Isaac-GR00T/pulls)
2. Provide a clear description of:
   * The problem being solved
   * Your solution approach
   * Links to related issues
3. Reference any relevant issues (e.g., "Fixes #123")

<Note>
  We look forward to reviewing your PR! Please be patient as maintainers review contributions.
</Note>

## Developer Certificate of Origin

By making a contribution to this project, you certify that:

<Accordion title="Developer's Certificate of Origin 1.1">
  ```
  Developer Certificate of Origin
  Version 1.1

  Copyright (C) 2004, 2006 The Linux Foundation and its contributors.

  Everyone is permitted to copy and distribute verbatim copies of this
  license document, but changing it is not allowed.

  Developer's Certificate of Origin 1.1

  By making a contribution to this project, I certify that:

  (a) The contribution was created in whole or in part by me and I
      have the right to submit it under the open source license
      indicated in the file; or

  (b) The contribution is based upon previous work that, to the best
      of my knowledge, is covered under an appropriate open source
      license and I have the right under that license to submit that
      work with modifications, whether created in whole or in part
      by me, under the same open source license (unless I am
      permitted to submit under a different license), as indicated
      in the file; or

  (c) The contribution was provided directly to me by some other
      person who certified (a), (b) or (c) and I have not modified
      it.

  (d) I understand and agree that this project and the contribution
      are public and that a record of the contribution (including all
      personal information I submit with it, including my sign-off) is
      maintained indefinitely and may be redistributed consistent with
      this project or the open source license(s) involved.
  ```
</Accordion>

## Code style guidelines

### Python code formatting

* Use `ruff format` for consistent formatting
* Use `ruff check --fix` for linting
* Follow PEP 8 guidelines
* Maximum line length: 100 characters (enforced by ruff)

### Documentation

* Write clear docstrings for all public functions and classes
* Use Google-style docstring format
* Update relevant documentation when changing functionality

### Commit messages

* Use clear, descriptive commit messages
* Start with a verb in present tense (e.g., "Add", "Fix", "Update")
* Reference issue numbers when applicable (e.g., "Fix #123: ...")

Example:

```
Add support for new embodiment tag

- Implement NEW_EMBODIMENT configuration
- Add tests for new modality config
- Update documentation

Fixes #456
```

## Testing guidelines

### Writing tests

* Place tests in `tests/` directory matching the source structure
* Name test files with `test_` prefix (e.g., `test_policy.py`)
* Use descriptive test function names (e.g., `test_get_action_with_valid_observation`)
* Include both positive and negative test cases
* Test edge cases and error conditions

### Test coverage

* Aim for high test coverage of new code
* Run tests locally before submitting PR
* CI will run full test suite on all supported platforms

## Continuous Integration

All pull requests run through our CI pipeline on [GitHub Actions](https://github.com/NVIDIA/Isaac-GR00T/actions), which checks:

* **Code formatting**: `ruff format --check`
* **Linting**: `ruff check`
* **Unit tests**: `pytest`
* **Type checking**: `mypy` (if configured)

Your PR must pass all CI checks before it can be merged.

## Getting help

If you need help with your contribution:

* Ask questions in your pull request
* Comment on related issues
* Check existing documentation and examples
* Review similar merged pull requests for guidance

## License

By contributing to Isaac GR00T, you agree that your contributions will be licensed under the Apache License 2.0.

```
SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```

## Thank you

Thank you for contributing to NVIDIA Isaac GR00T! Your contributions help advance the state of robotics research and make foundation models more accessible to the community.