maintain-packaging

Maintain Release And Packaging Surfaces

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 a change affects how NeMo Fabric is built, packaged, named, or consumed outside the source tree.

Audit Areas

• Rust Cargo.toml package names and workspace metadata
• Root development coordination in pyproject.toml
• Published Python package metadata under sdk/python/ and adapter-contract/python/
• Native extension naming and placement under sdk/python/nemo-fabric-runtime/src/nemo_fabric
• Dependency resolution in Cargo.lock and uv.lock
• TypeScript adapter-contract metadata and dependency resolution in adapter-contract/typescript/package.json and package-lock.json
• Documentation tooling metadata in docs/package.json and docs/package-lock.json
• CI workflows, install commands, and example commands
• npm trusted publishing through .github/workflows/publish_typescript.yml and the protected npmjs environment
• justfile build, test, clean, and documentation recipes
• Release tags, registry publication, and release-facing documentation in RELEASING.md

Dependency Selection

Treat every direct dependency as a long-lived API, supply-chain, and licensing commitment.

• Keep nemo-fabric as a metapackage that unconditionally installs the exact-version nemo-fabric-runtime distribution. Its harness extras delegate to version-matched leaf adapter harness extras. Hermes Agent is the sole exception: its root extra delegates to the bare adapter because Hermes Agent 0.20 and later is not installable from PyPI. Do not add other adapter-only aliases.

• Keep the runtime streaming extra pinned to the version-matched nemo-fabric-collector distribution. The metapackage streaming extra must delegate to the version-matched runtime extra. Do not expose a separate metapackage collector extra.

• Keep leaf adapters adapter-only by default. Every leaf provides full, and every package-installable harness provides harness. The Hermes adapter omits harness because users install Hermes Agent separately from source. Provide relay only when the adapter imports the NeMo Relay Python package. For adapters that launch the Relay CLI, both harness and full install the version-matched nemo-relay-cli-bin package and remain equivalent.

• First prefer the standard library, an existing dependency, or a small local implementation when it keeps the behavior clear and maintainable.

• When multiple dependencies satisfy the technical requirement, prefer the maintained OSS option with clear SPDX metadata, a smaller transitive graph, and permissive terms such as Apache-2.0, MIT, BSD, or ISC.

• Inspect the resolved transitive graph, not only the direct package license.

• Treat UNKNOWN, non-SPDX/custom, proprietary or source-available terms, and copyleft or network-copyleft terms as explicit review points. Do not silently accept or reject them; route them to the dependency approvers with the distribution and linkage context.

• Record the functional need, viable alternatives considered, why the selected dependency is the narrowest fit, and any unresolved licensing question.

• Run uv run --no-project python scripts/licensing/license_diff.py --base-ref origin/main after updating manifests and lockfiles, then review added packages and license changes.

• For adapter-contract/typescript/package-lock.json, inspect the resolved package entries and their license fields. The adapter-contract package must keep an empty production dependency graph; build-only dependencies still require permissive, recorded license evidence.

• Regenerate the attribution files with the named pre-commit hooks instead of editing generated output:

  uv run pre-commit run --all-files attributions-rust
  uv run pre-commit run --all-files attributions-python
  uv run pre-commit run --all-files attributions-node

The license diff is evidence for reviewers. Dependency approvers make compatibility decisions using the distribution and linkage context.

Checklist

• Package names, import paths, and module names are internally consistent
• Generated artifacts still land where downstream consumers expect
• Docs and examples use the current install/import/build commands
• CI references the same package names as local workflows
• Public packaging changes are reflected in release-facing docs
• Workspace, Python, and lockfile versions remain aligned where required
• The TypeScript adapter-contract package version follows the workspace release version without changing its independent wire contract version
• The editable maturin build still produces nemo_fabric._native
• New dependencies are necessary, maintained, and narrower than the viable alternatives
• Direct and transitive license changes were reviewed from the resolved lockfiles
• Licensing uncertainties are called out for dependency approver review
• Changed attribution files are regenerated and included

References

• pyproject.toml
• RELEASING.md
• sdk/python/nemo-fabric/pyproject.toml
• sdk/python/nemo-fabric-runtime/pyproject.toml
• adapter-contract/python/pyproject.toml
• Cargo.toml
• Cargo.lock
• uv.lock
• docs/package.json
• docs/package-lock.json
• adapter-contract/typescript/package.json
• adapter-contract/typescript/package-lock.json
• .github/workflows/ci_typescript.yml
• .github/workflows/publish_typescript.yml
• scripts/ci/publish_typescript_package.py
• .github/workflows/ci_python.yml
• .github/workflows/ci_rust.yml
• .pre-commit-config.yaml
• scripts/licensing/license_diff.py
• justfile