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.

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

1. Confirm that sdk/python/nemo-fabric-runtime/pyproject.toml remains dynamic

and unchanged.

1. 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:

• setprojectversion must call the Cargo, Python, and TypeScript project

version helpers.

• setcargoworkspace_version must update the workspace version and the

nemo-fabric-core workspace dependency, then verify every nemo-fabric-* workspace package through Cargo metadata.

• setpythonproject_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.

• settypescriptproject_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