Contributing to NVIDIA NeMo Fabric
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:
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:
The resulting wheel files are placed in the dist/ directory. Install the
packages into a virtual environment with:
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:
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.0for stable releases. - Use
v0.1.0-rc.1for prereleases. - Do not use tags such as
0.1.0or0.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:
If the virtual environment is already synchronized, use no_uv=true to avoid
reinstalling dependencies:
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:
- Confirm that
README.mdreflects the current workspace, supported adapters, and top-level documentation. - Update the relevant SDK or API reference docs for public API changes.
- Update the relevant adapter or example
README.mdwhen that surface changes. - Update embedded examples, integration docs, and adapter-support notes to reflect the current behavior.
- For docs site changes, run
just docsto 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:This will append the following to your commit message: - Full text of the DCO (https://developercertificate.org/):
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.
- 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. - Set repository variable
PR_CLEANUP_APPLYtotrueto enable automatic comments and closures after merge. Leave it unset for automatic dry-run reports. Manual dispatch defaults to reporting only; selecting itsapplyinput explicitly requests enforcement for that run, regardless of the automatic setting. Existing excess PRs are included in enforcement. - To pause closures, unset
PR_CLEANUP_APPLYand 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:
Before Submitting
Complete these checks before opening or updating a pull request:
- 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.
- Run the relevant test suites and confirm they pass.
- Verify the affected packages compile with
just build-rust,just build-python, orjust build-all. - Update the relevant documentation entry points and references.
- Rebase your branch on the latest
mainto 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:
Valid types:
Examples:
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:
Python:
HTML / Markdown:
For MDX files, use a JSX comment:
TOML / YAML / shell:
Reviewers will check SPDX headers during review.