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`