# Update Project Version

> Update the NVIDIA NeMo Fabric release version across Cargo, Python, and TypeScript package metadata, internal Python dependency pins, integration metadata, and lockfiles. Use when bumping, synchronizing, or auditing NeMo Fabric package versions for a release.

- Skill: `nvidia/update-project-version` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add nvidia/update-project-version`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nvidia/update-project-version/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: Apache-2.0
- Author: NVIDIA (https://skillmd.com/u/nvidia)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nvidia/update-project-version

---



# Update Project Version

## Companion Guidance

Use `karpathy-guidelines` alongside this skill for implementation or review
work. Keep changes scoped, surface assumptions, and define focused validation
before editing.

Use this skill when changing the NeMo Fabric version, including
pre-release or build-metadata variants used during packaging.

## Source Of Truth

- `Cargo.toml` `[workspace.package].version` is the source of truth for the Rust
  workspace and the release version stamped into Python and TypeScript package
  metadata.
- Keep `Cargo.toml` `[workspace.dependencies]` self-references aligned when the
  workspace version changes.
- `sdk/python/nemo-fabric-runtime/pyproject.toml` is the exception among the
  Python projects: do not add a literal `project.version`. Keep
  `project.dynamic = ["version"]` because Maturin derives
  `nemo-fabric-runtime`'s version from
  `crates/fabric-python/Cargo.toml`, which inherits the workspace version.
- The setuptools projects do not derive their versions from Cargo. Update the
  literal `project.version` in every one of these files:
  - `sdk/python/nemo-fabric/pyproject.toml`
  - `adapter-contract/python/pyproject.toml`
  - `adapters/python/*/pyproject.toml`
- Keep internal Python package requirement pins aligned with the Python release
  version:
  - The unconditional `nemo-fabric-runtime == <version>` dependency in the
    published `sdk/python/nemo-fabric/pyproject.toml`.
  - All `nemo-fabric-* == <version>` requirements in its optional dependencies.
  - Each adapter's `nemo-fabric-adapters-common == <version>` dependency.
- Keep `adapter-contract/typescript/package.json` and the root package entries in
  its `package-lock.json` aligned with the Cargo SemVer release version.

For a normal release, use the same `X.Y.Z` string everywhere. For a prerelease
or build-metadata version, use valid Cargo SemVer in `Cargo.toml` and the
equivalent PEP 440 version in explicit Python metadata. Confirm that the
Maturin-built runtime and setuptools-built packages resolve to equivalent
versions rather than blindly copying incompatible syntax.

## Workflow

1. Read the current version from `Cargo.toml` and decide the exact Cargo,
   Python, and TypeScript target version strings.
2. Run `just set-version <cargo-version>`. The recipe preserves the normalized
   SemVer for Cargo and TypeScript, converts it to PEP 440 for Python, and
   updates:
   - `Cargo.toml` `[workspace.package].version`
   - `Cargo.toml` `workspace.dependencies.nemo-fabric-core.version`
   - The setuptools `project.version` in the published SDK metapackage,
     Python adapter contract, and every adapter `pyproject.toml`
   - Every internal `nemo-fabric-*` exact-version requirement
   - The TypeScript adapter-contract `package.json` and `package-lock.json`
   - `Cargo.lock` through Cargo metadata resolution
   - The root, runtime, and adapter `uv.lock` files through `just lock-python`
3. Confirm that `sdk/python/nemo-fabric-runtime/pyproject.toml` remains dynamic
   and unchanged.
4. Audit references to the old version with targeted searches. Distinguish
   package-version surfaces from examples and unrelated dependency versions.

If editing the helper code, keep these contracts aligned:

- `set_project_version` must call the Cargo, Python, and TypeScript project
  version helpers.
- `set_cargo_workspace_version` must update the workspace version and the
  `nemo-fabric-core` workspace dependency, then verify every `nemo-fabric-*` workspace
  package through Cargo metadata.
- `set_python_project_versions` must update the published SDK metapackage,
  Python adapter contract, every adapter `pyproject.toml` discovered under
  `adapters/python/`, and all internal exact-version pins while
  rejecting a static version in
  `sdk/python/nemo-fabric-runtime/pyproject.toml`.
- `set_typescript_project_version` must update the package manifest and both
  root version entries in the npm lockfile without changing dependency versions.
- The `set-version` recipe must run `just lock-python` after source metadata is
  updated.

## Validation

- Inspect Cargo version fields:
  `rg -n '^version =|nemo-fabric-core = \{ path = .*version =' Cargo.toml`
- Inspect explicit Python versions and internal pins:
  `rg -n '^version =|nemo-fabric-[a-z-]+(?:\[[^]]+\])? == ' pyproject.toml sdk adapter-contract/python adapters/python --glob 'pyproject.toml'`
- Confirm the runtime remains dynamic:
  `rg -n 'dynamic = \["version"\]' sdk/python/nemo-fabric-runtime/pyproject.toml`
- Inspect the TypeScript package and lockfile root versions:
  `rg -n '"version":' adapter-contract/typescript/package{,-lock}.json`
- Run `cargo check --workspace --locked`.
- Run `just build-python` to verify all Python package metadata resolves.
- Run `just test-python` when the integration version or Python packaging
  behavior changes materially.
- Run `just wheels` for release-facing validation of every Python wheel.
- Run `just pack-typescript` to verify the stamped TypeScript package metadata.
- Run `git diff --check`.

## Avoid

- Updating only `Cargo.toml` and leaving the setuptools packages stale.
- Adding a literal version to `sdk/python/nemo-fabric-runtime/pyproject.toml`;
  Maturin owns that version.
- Updating Python package versions without their exact internal dependency pins.
- Forgetting `Cargo.lock`, the root `uv.lock`, or per-project `uv.lock` files.
- Updating the TypeScript package manifest without its npm lockfile root entry.
- Blind repository-wide replacement of version-like strings.

## References

- `Cargo.toml`
- `Cargo.lock`
- `pyproject.toml`
- `uv.lock`
- `sdk/python/nemo-fabric/pyproject.toml`
- `sdk/python/nemo-fabric/uv.lock`
- `sdk/python/nemo-fabric-runtime/pyproject.toml`
- `sdk/python/nemo-fabric-runtime/uv.lock`
- `adapter-contract/python/pyproject.toml`
- `adapter-contract/python/uv.lock`
- `adapters/python/*/pyproject.toml`
- `adapters/python/*/uv.lock`
- `adapter-contract/typescript/package.json`
- `adapter-contract/typescript/package-lock.json`
- `justfile`