Validate Change

---
name: validate-change
description: Choose and run the right NeMo Relay validation matrix for a change instead of using one fixed test list
author: NVIDIA Corporation and Affiliates
license: Apache-2.0
---


# Validate a Change

## 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 to choose the smallest validation set that still covers the
surfaces touched by a change.

## Mandatory Rules

- Format changed files with the language-native formatter before the final
  lint/test pass.
- If any Rust code changed, always run `just test-rust`.
- If any Rust code changed, also run `cargo fmt --all`.
- If any Rust code changed, also run `cargo clippy --workspace --all-targets -- -D warnings`.
- If `crates/core` or `crates/adaptive` changed, run the full matrix across Rust,
  Python, Go, and Node.js.
- If a language surface changed, always run that language's test target even when
  Rust core did not change.
- If dynamic plugin behavior changed, use `maintain-dynamic-plugins` and include
  the native SDK, worker protocol, Python SDK, docs, packaging, and Codecov
  surfaces in the validation plan.
- If code changes alter APIs, bindings, commands, paths, packaging behavior,
  observability/adaptive semantics, or documented best practices, update any
  dependent maintainer or consumer skills in the same branch.
- During iteration, prefer `uv run pre-commit run --files <changed files...>`.
- Before review or handoff, run `uv run pre-commit run --all-files`.

## Start With The Change Shape

- **Core runtime or shared semantics changed**
  Use `test-rust-core`. This always includes `just test-rust`,
  `cargo fmt --all`, `cargo clippy --workspace --all-targets -- -D warnings`,
  and the full matrix across Rust, Python, Go, and Node.js.
- **Python-only wrapper or binding change**
  Use `test-python-binding`.
- **Go binding change**
  Use `test-go-binding`.
- **Node.js binding change**
  Use `test-node-binding`.
- **FFI surface change**
  Use `test-ffi-surface`.
- **Framework integration change**
  Run the relevant language test target and focused integration tests or smoke
  path.
- **Dynamic plugin loader, SDK, or protocol change**
  Use `maintain-dynamic-plugins`. Run the targeted plugin crates and
  `just test-python-plugin` first, then escalate to the core validation matrix
  when runtime behavior or `crates/core` changed.
- **Docs-only change**
  Run targeted checks only if commands, package names, or examples changed.
  Use `just docs` for docs-site builds and `just docs-linkcheck` when links
  changed. The `./scripts/build-docs.sh` wrapper remains available for
  compatibility.

## Core Validation Matrix

```bash
just test-rust
just test-python
just test-go
just test-node
```

## Common Targeted Commands

```bash
# Rust only
just build-rust
just test-rust
just ci=true test-rust
cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings

# Python
just build-python
just build-python-plugin
just test-python
just test-python-plugin
uv run ruff format python
uv run pytest -k "<pattern>"

# Go
just build-go
just test-go
cd go/nemo_relay && go fmt ./...

# Node
just build-node
just test-node
npm run format --workspace=nemo-relay-node

# Docs site
just docs
just docs-linkcheck
```

## Layer-Specific Skills

- `test-rust-core`
- `test-python-binding`
- `test-go-binding`
- `test-node-binding`
- `test-ffi-surface`
- `maintain-dynamic-plugins`

## Pre-commit Semantics

Use pre-commit in two modes:

- During iteration, run `uv run pre-commit run --files <changed files...>`.
- Before review or handoff, run `uv run pre-commit run --all-files`.

Important: `--files` still triggers any matching hook whose `files` or `types`
selectors match the provided paths. Some hooks then ignore filenames and run a
whole-language or workspace-wide command because they are configured with
`pass_filenames: false`.

Examples from this repo:

- Matching Python files run Ruff on the selected files, and also trigger
  `ty check . ...` for the Python project.
- Matching Rust files trigger `cargo fmt --all --`, `cargo clippy --workspace --all-targets -- -D warnings`,
  and `cargo check --workspace --all-targets`.
- Matching Go files trigger `gofmt` on the selected files and `go vet ./...`.
- Matching docs markdown files under `README.md`, `CONTRIBUTING.md`, or `docs/`
  trigger the docs link checker.
- Matching `Cargo.toml`, `Cargo.lock`, or `deny.toml` triggers `cargo deny check`.
- Matching `Cargo.lock`, `uv.lock`, or `package-lock.json` triggers
  the attributions generators.
- Matching Node.js public JS/TS surfaces can also trigger the public docstring
  checks, while matching Node.js JS/TS files trigger the prettier wrapper.

## Hygiene Checks

Run these whenever the change is headed for review. Rust changes should still
run `cargo fmt --all` and `cargo clippy --workspace --all-targets -- -D warnings`
even if you also plan to rely on pre-commit.

```bash
cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
uv run pre-commit run --all-files
```

If the change is large or public-facing, also verify:

- README and docs entry points still match current package names and paths
- Examples still run with the documented commands
- Any renamed public surfaces are reflected consistently in manifests and docs
- Dynamic plugin examples exclude Relay versions before 0.8. The recommended
  range is `compat.relay = ">=0.8.0,<1.0"`; open-ended or narrower
  0.8-or-newer ranges are valid when intentional.

## References

- Testing guide: `docs/contribute/testing-and-docs.mdx`
- Contributor guide: `CONTRIBUTING.md`
- Build and test dispatchers: `justfile`