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