Skip to navigation

Contributing to NVIDIA NeMo Fabric

View as MarkdownOpen in Claude

Thank you for your interest in contributing to NeMo Fabric. This guide covers the development workflow, coding standards, and pull request process.

Contribution Access

Anyone with a GitHub account may create or comment on an issue in this public repository. Pull request creation is limited to approved users in the NeMo-Fabric-developers group. General changes require CODEOWNER approval from NeMo-Fabric-reviewers, a subset of the developer group. Documentation and dependency changes use their specialized approver groups.

For non-security contributions, external contributors should open an issue with a reproducer, proposed design, or patch description. A NeMo Fabric maintainer can adopt the work into a pull request when appropriate. Do not report security vulnerabilities through a public issue or pull request; follow the security policy. Public issue and pull request comments remain welcome and do not require developer access.

Development Setup

This section collects the setup steps needed before building, testing, or contributing changes.

Source Development

Install these tools before you start:

  • Rust (stable toolchain) — install with rustup
  • Python 3.12 or 3.13 for the all-packages build below
  • Node.js >= 22.19.0 with npm
  • uv — follow the uv installation guide
  • just >= 1.50.0 — cargo install just --locked

Clone the repository, create a virtual environment, and build the Rust, Python, and TypeScript packages:

git clone https://github.com/NVIDIA/NeMo-Fabric.git
cd NeMo-Fabric
uv venv --seed .venv --python 3.13
source .venv/bin/activate
just install-hermes-agent
uv sync --all-groups --all-extras
just no_uv=true build-all

The all-packages build installs NOOA, which requires Python 3.12 or 3.13. Keep the default 3.13 or use 3.12. For other supported Python versions, follow Development Setup and Building from Source.

Verify the checkout by running the test suites described in Testing.

Package Installation

To build Python packages (wheels) locally from a source checkout:

just wheels

The resulting wheel files are placed in the dist/ directory. Install the packages into a virtual environment with:

uv pip install --find-links ./dist nemo-fabric

Hermes Agent 0.20 and later is not installable from PyPI. For local development, check out the pinned Hermes source and synchronize it into its separate Python 3.14 environment with:

just install-hermes-agent

The recipe checks out Hermes Agent under external/hermes-agent and installs it with the adapter into .venv-hermes, separately from the active .venv. Run Hermes tests with just test-hermes, which uses that interpreter.

For a Hermes application launched from .venv, run export ADAPTER_PYTHON="$PWD/.venv-hermes/bin/python" from the repository root. Refer to the Hermes adapter setup for application configuration.

End users should follow the Hermes Agent installation guide and install nemo-fabric-adapters-hermes without a harness extra.

Refer to the installation guide for the complete list of adapters and installation options.

Release Tagging

Release tags use SemVer with a leading v.

  • Use v0.1.0 for stable releases.
  • Use v0.1.0-rc.1 for prereleases.
  • Do not use tags such as 0.1.0 or 0.1.0-rc.1.

Code Style

These style requirements keep contributions consistent across Rust, Python, and general repository files.

Rust

Use these commands and conventions when changing the core runtime, CLI, or native Python extension:

  • Formatting: cargo fmt --all
  • Format check: cargo fmt --all -- --check
  • Compilation check: cargo check --workspace --locked

Python

Follow the existing style in the Python SDK, adapters, examples, and tests. Use type annotations for public APIs and keep native binding declarations in sync with their Rust implementations.

TypeScript

Use strict TypeScript for the adapter-contract binding. Preserve the JSON wire property names, run the checked-in generator instead of editing generated declarations, and keep production dependencies out of the contract package.

General

Use the naming conventions appropriate to each language. Rust and Python use snake_case for functions and variables. Rust, Python, and TypeScript types use PascalCase. TypeScript contract properties preserve the wire snake_case names.

Testing

Run tests for every language surface affected by your changes. If a change touches the Rust core or public adapter-contract schemas, run the Rust, Python, and TypeScript suites because both language bindings depend on the generated wire contract.

Run the affected test targets through the repository justfile:

# Rust workspace
just test-rust
# Python SDK, adapters, integrations, and examples
just test-python
# TypeScript adapter contract
just test-typescript
# All supported language surfaces
just test-all

If the virtual environment is already synchronized, use no_uv=true to avoid reinstalling dependencies:

just no_uv=true test-python
just no_uv=true test-all

When adding functionality, include tests in the corresponding Rust crate or in the relevant area under tests/. Public contract changes must keep the checked-in JSON Schema snapshots, Python representations, and generated TypeScript declarations synchronized.

Documentation Checklist

If your change affects public behavior, adapters, examples, or workspace structure, update the corresponding documentation in the same branch.

Before opening a PR, check the following:

  1. Confirm that README.md reflects the current workspace, supported adapters, and top-level documentation.
  2. Update the relevant SDK or API reference docs for public API changes.
  3. Update the relevant adapter or example README.md when that surface changes.
  4. Update embedded examples, integration docs, and adapter-support notes to reflect the current behavior.
  5. For docs site changes, run just docs to regenerate the Python and Rust API references and validate the Fern configuration.

For documentation-heavy changes, prefer small targeted commits so the history clearly separates entry-point changes, reference changes, examples, and maintenance updates.

DCO Sign-Off

  • We require that all contributors “sign-off” on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license.
    • Any contribution which contains commits that are not Signed-Off will not be accepted.
  • To sign off on a commit you simply use the --signoff (or -s) option when committing your changes:
    $ git commit -s -m "Add cool feature."
    This will append the following to your commit message:
    Signed-off-by: Your Name <your@email.com>
  • Full text of the DCO (https://developercertificate.org/):
    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.

Pull Request Process

This section describes how to prepare and submit changes for review.

PR Cleanup Policy

The PR Cleanup workflow enforces the following rules when automatic enforcement is enabled. Manual runs default to dry-run mode, reporting proposed closures without posting comments or closing PRs.

  • Each author may have up to 3 open PRs, including drafts, across all target branches. Cleanup keeps the three oldest by original creation time and closes newer excess PRs. Maintainers are exempt from this cap.
  • PRs with more than 28 days without activity, including drafts, are closed regardless of author, including maintainers. Human comments and edits, reviews and review comments, reopening, and pushes count as activity. Bot comments, CI results, labels, and draft/ready transitions alone do not count.

Each closure explains its reason. To resume an inactive PR, reopen it when ready and tag maintainers for review. To reopen a PR closed for exceeding the cap, first merge or close another PR. Reopening preserves original creation order and triggers policy evaluation again. Branches and discussions are preserved.

Cleanup runs when PRs open, reopen, or receive commits, and daily. It acts after PR creation, so an excess PR may briefly appear and trigger CI.

Maintainer Setup and Rollout

The configuration is in .github/pr-cleanup.json; the implementation and tests are in scripts/ci/pr_cleanup.py and tests/scripts/test_pr_cleanup.py.

The workflow uses the built-in repository GITHUB_TOKEN; no additional App or credentials are required. The maintainer exemption list is maintained in the policy configuration and should be updated when maintainers change.

  1. Confirm the organization/repository Actions event policy permits pull_request_target. The workflow executes only trusted default-branch code, never PR-head code. Allow the pinned actions in the organization’s action policy. Manual dispatch is restricted to the default branch.
  2. Set repository variable PR_CLEANUP_APPLY to true to enable automatic comments and closures after merge. Leave it unset for automatic dry-run reports. Manual dispatch defaults to reporting only; selecting its apply input explicitly requests enforcement for that run, regardless of the automatic setting. Existing excess PRs are included in enforcement.
  3. To pause closures, unset PR_CLEANUP_APPLY and avoid manual apply runs, or disable the workflow. Previously closed PRs are not automatically reopened.

Push timing is observed and saved in the workflow’s pr-cleanup-state artifact; commit author dates are not used as push timestamps. New PRs, missing/expired state, or an observation gap of at least 28 days start a fresh 28-day observation period. Consequently, the first deployment does not immediately close old PRs for inactivity. Dry-run observation history carries forward into enforcement. Keep artifact retention at least 28 days and do not delete the latest history unless you intend to restart observation. Comment and review history is read with pagination before an inactivity decision. Failed lookups skip affected closures and appear in the workflow summary. Rechecks reduce races with human activity, but GitHub does not offer atomic read-and-close operations.

Local read-only inspection with an authenticated gh CLI:

GH_TOKEN="$(gh auth token)" python3 scripts/ci/pr_cleanup.py --repo NVIDIA/NeMo-Fabric
python3 -m unittest discover -s tests/scripts -p test_pr_cleanup.py -v

Before Submitting

Complete these checks before opening or updating a pull request:

  1. Open or identify an issue describing the proposed enhancement or bug fix. External contributors should use a GitHub issue; NVIDIA contributors may use a GitHub or Linear issue.
  2. Run the relevant test suites and confirm they pass.
  3. Verify the affected packages compile with just build-rust, just build-python, or just build-all.
  4. Update the relevant documentation entry points and references.
  5. Rebase your branch on the latest main to avoid merge conflicts.

PR Description

Complete the pull request template:

  • Overview: Summarize the change and explain why it is needed.
  • Where should the reviewer start?: Point to the most important file, test, or design decision.
  • Related issues: Link the issue with the appropriate action keyword.
  • Testing: List the checks you ran and any tests you added.
  • Breaking changes: Call out public API or configuration changes that affect existing users.

Review Expectations

  • All PRs require at least one approving review before merge.
  • Reviewers may request changes for code quality, test coverage, documentation, or design concerns.
  • Address review feedback by pushing additional commits; do not force-push during review.
  • CI must pass before merging.

Commit Message Conventions

Use the following format for commit messages:

type: short description of the change
Optional longer description explaining the motivation and context.

Valid types:

TypePurpose
featNew feature or capability
fixBug fix
docsDocumentation changes
testTest additions or modifications
refactorCode restructuring without behavior changes
choreBuild, CI, or tooling changes
perfPerformance improvements

Examples:

feat: add typed runtime diagnostics
fix: preserve adapter errors in run results
docs: clarify Hermes Agent adapter installation
test: cover concurrent Python runtime invocations

Keep the first line under 72 characters. Use the body for additional context when the change is not self-explanatory.

SPDX License Headers

All source files must include an SPDX license header. Use the appropriate comment syntax for the file type.

Rust:

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

Python:

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

HTML / Markdown:

<!--
SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0
-->

For MDX files, use a JSX comment:

{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0 */}

TOML / YAML / shell:

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

Reviewers will check SPDX headers during review.