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 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
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.)

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

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 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)

1. Fork the repository

   Fork the Isaac GR00T repository on GitHub.

2. Clone your fork

   Clone your fork locally:

   git clone https://github.com/USERNAME/Isaac-GR00T.git
   # or
   git clone [e-mail]:USERNAME/Isaac-GR00T.git
   
3. Add upstream remote

   Add the main repository as an upstream remote:

   git remote add upstream https://github.com/NVIDIA/Isaac-GR00T.git
   

   Verify your remotes:

   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)
   
4. Install in editable mode

   Create a development environment and install GR00T in editable mode:

   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.

Keeping your fork up-to-date

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

git checkout main  # if not already on main
git pull --rebase upstream main
git push

Creating a branch for your changes

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

Create a new branch:

# 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 for code formatting and linting.

Many IDEs support ruff as a plugin, allowing automatic formatting on save. For example, black.vim provides this functionality in Vim.

Run ruff from the command line:

# 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:

# 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:

pytest -v tests/gr00t/policy/test_policy.py

Opening a pull request

After all checks have passed:

1. Open a new GitHub pull request
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”)

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

Developer Certificate of Origin

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

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.

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, 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.