Newton is a project of the Linux Foundation and aims to be governed in a transparent, accessible way for the benefit of the community. All participation in this project is open and not bound to corporate affiliation. Participants are all bound to the Linux Foundation Code of Conduct.
Please refer to the contribution guidelines in the newton-governance repository for general information, project membership, and legal requirements for making contributions to Newton.
If you contribute as part of your employment, your organization must be set up in LFX EasyCLA for Newton and complete a Corporate Contributor License Agreement (CCLA). Opening a pull request against an EasyCLA-enabled Newton repository triggers the EasyCLA check. If authorization is required, the check displays the prompt and link for starting or completing the appropriate CLA workflow.
If your organization is not listed, the EasyCLA workflow lets you add it and identify the representative authorized to coordinate the CCLA signing process. See Contributor License Agreements for the full process.
Newton welcomes contributions from the community. In order to avoid any surprises and to increase the chance of contributions being merged, we encourage contributors to communicate their plans proactively by opening a GitHub Issue or starting a Discussion in the corresponding repository. Keep each pull request focused on a single feature or bug fix, and write clear, concise commit messages.
Use the development guide for environment setup and development workflows. Code and public API changes must follow the source code and public API guidelines. Reviewers may use the suggested review guidelines.
There are several ways to participate in the Newton community:
- Help answer questions or contribute to technical discussion in GitHub Discussions and Issues.
- If you have a question, suggestion or discussion topic, start a new GitHub Discussion if there is no existing topic.
- Once somebody shares a satisfying answer to the question, click "Mark as answer".
- GitHub Issues should only be used for bugs and features. Specifically, issues that result in a code or documentation change. We may convert issues to discussions if these conditions are not met.
- Check in the GitHub Issues if a report for the bug already exists.
- If the bug has not been reported yet, open a new Issue.
- Use a short, descriptive title and write a clear description of the bug.
- Document the Git hash or release version where the bug is present, and the hardware and environment by including the output of
nvidia-smi. - Add executable code samples or test cases with instructions for reproducing the bug.
- Create a new issue if there is no existing report, or
- directly submit a fix following the "Fixing a Bug" workflow below.
- Ensure that the bug report issue has no assignee yet. If the issue is assigned and there is no linked PR, you're welcome to ask about the current status by commenting on the issue.
- Write a fix and regression unit test for the bug following the source code guidelines.
- Open a new pull request for the fix and test.
- Write a description of the bug and the fix.
- Mention related issues in the description: E.g. if the patch fixes Issue #33, write Fixes #33.
- Have a signed CLA on file (see Legal Requirements).
- Have the pull request approved by a Project Member and merged into the codebase.
- Write an optimization that improves an existing or new benchmark following the source code guidelines.
- Open a new pull request with the optimization, and the benchmark, if applicable.
- Write a description of the performance optimization.
- Mention related issues in the description: E.g. if the optimization addresses Issue #42, write Addresses #42.
- Have a signed CLA on file (see Legal Requirements).
- Have the pull request approved by a Project Member and merged into the codebase.
- Discuss your proposal ideally before starting with implementation. Open a GitHub Issue or Discussion to:
- propose and motivate the new feature;
- detail technical specifications;
- and list changes or additions to the Newton API.
- Wait for feedback from Project Members before proceeding.
- Implement the feature following the source code guidelines.
- Add comprehensive testing and benchmarking for the new feature.
- Ensure all existing tests pass and that existing benchmarks do not regress.
- Update or add documentation for the new feature.
- Have a signed CLA on file (see Legal Requirements).
- Have the pull request approved by a Project Member and merged into the codebase.
Newton is designed to be extended outside this repository. Most new solvers and domain-specific extensions should start as separate packages that depend on Newton, so the solver authors can own their maintenance, documentation, testing, and release cadence.
When developing an external solver or extension:
- publish it in its own repository or package with a dependency on Newton;
- use public Newton APIs only; do not import from
newton._src; - keep solver-specific tests, examples, and documentation with the external project;
- open a separate GitHub Issue or Discussion if you need new public extension points in Newton;
- add the
newton-physicsGitHub topic to the repository for discoverability.
If an external solver or extension becomes broadly useful and has clear long-term maintainers, Project Members may decide case-by-case to adopt part or all of it into the main Newton repository. This is conservative and not guaranteed. Contributors should not rely on upstream adoption as the expected path.
The bar for adding a solver to the main Newton repository is high because every upstream solver adds API, testing, review, release, and support responsibilities for the project. Project Members may ask that a solver remain external, or that only smaller reusable API hooks or improvements be contributed upstream.
Before investing in an upstream solver contribution, open a GitHub Issue or Discussion and wait for feedback from Project Members. Include:
- the solver's scope, algorithms, and expected users;
- why it should live in the main Newton repository instead of an external package;
- the proposed Newton API additions or changes;
- the long-term maintenance plan and owners;
- tests, benchmarks, examples, and documentation you expect to provide.
The same expectations apply to control laws and actuator components as to solvers: Newton provides the composable building blocks and extension points, while domain- or asset-specific behavior is generally owned by the projects that use it.
Newton core carries a small set of control laws and actuator components that are broadly used across robots, such as PD and PID control, neural policies, effort clamping, and actuation delay. Control laws that model a specific mechanism or product should be implemented on the user side using the public actuator API.
A control law or actuator component is a candidate for the main Newton repository when:
- it applies across many robots or benchmarks rather than to one mechanism or product family;
- it cannot be expressed by composing existing public components;
- it has clear long-term maintainers within the project.
Everything else is better maintained externally. Instead of contributing a specialized control law upstream, consider contributing an example that shows how to implement and register a user-supplied one, or a pull request for the public extension points you are missing.
As with solvers, open a GitHub Issue or Discussion and wait for feedback from Project Members before investing in an upstream contribution.
Newton generally does not maintain a library of tuned or verified simulation content, such as actuator models, sensor models, robot models, calibrated material parameters, datasets, or trained policies. These assets are often tied to specific OEM products, firmware versions, calibration processes, validation datasets, or support commitments. They should be owned and maintained by the OEM, lab, or user project that can validate and support them.
Newton's role is to provide the public APIs, capabilities, tooling, workflows, examples, and tests needed for externally maintained models to work with Newton. If Newton is missing functionality that prevents you from building, tuning, validating, or distributing your own model assets, submit a pull request for the required Newton functionality, documentation, examples, or extension points rather than adding the tuned assets themselves to the main Newton repository.
When publishing externally maintained model assets:
- Host them in their own repository or package.
- Use public Newton APIs only; do not import from
newton._src. - Document ownership, license, supported Newton versions, what was and was not validated, and support expectations.
- Include tests or validation examples with the external project.
- Add the
newton-physicsGitHub topic to the repository for discoverability.
The Newton project may host simulation assets in the newton-assets repository when they are needed to test, document, or demonstrate Newton's core functionality. The newton-assets repository is not a general content library for OEM, lab, or user-maintained tuned models.
For example, a calibrated URDF for a specific robot should live in the maintainer's own repository, while a generic URDF used to test a Newton importer or document a Newton feature may belong in newton-assets.
Before proposing to add project-maintained assets:
- Make sure that the assets are properly licensed for use and distribution. If you are unsure about the license, open a new discussion.
- If a pull request in the main Newton repository relies on new assets, open a corresponding pull request in the newton-assets repository.
- Follow the instructions in the README of the
newton-assetsrepository. - Have a signed CLA on file (see Legal Requirements).
- Have the
newton-assetspull request approved by a Project Member and merged into the asset repository.