> This page is for NodeWright, version Latest · v0.21.0 (default).
> For other versions, use one of these documentation indexes:
> - Latest · v0.21.0 (default): https://docs.nvidia.com/nodewright/v0.21.0/llms.txt
> - v0.19.0: https://docs.nvidia.com/nodewright/v0.19.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nodewright/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nodewright/_mcp/server.

# NodeWright Versioning Strategy

NodeWright uses independent versioning for three components, all following [Semantic Versioning](https://semver.org/):

1. **Operator** - Kubernetes operator that manages NodeWright resources
2. **Agent** - Container that executes package operations on nodes  
3. **Chart** - Helm chart for deploying the operator
   1. NOTE: the versioning of the chat also includes versioning of the expected agent version. 
   2. NOTE: If changing either the operator or agent this will generally include a chart release too.

## Git Tagging Convention

```bash
operator/v{version}    # Operator releases
agent/v{version}       # Agent releases  
chart/v{version}       # Chart releases
cli/v{version}         # CLI (kubectl-nodewright) releases
```

## Component Versioning

### Operator & Agent

- **Independent versioning** with their own release cycles
- **Semantic versioning**: MAJOR.MINOR.PATCH
- **Compatibility**: Maintained through well-defined interfaces

The agent has been implemented in Go since the cutover (#222) and continues the
existing `agent/vx.y.z` version stream rather than starting a new component:
`agent/v6.x` tags are the Python implementation, and the first Go release is
`agent/v7.0.0`, a major bump for the build-stack change. The operator-facing
contract (arguments, environment variables, exit codes, and the on-host state
paths) is unchanged; the behaviour differences are listed in
`agent/RELEASE_NOTES.md`.

### Helm Chart  

- **Independent from operator/agent** (starting at v0.8.0 these will start to diverge in version number)
- **Chart version** (`version`): Tracks chart template/config changes
- **App version** (`appVersion`): Recommended stable operator version

## Chart Behavior

### Chart.yaml

example:
```yaml
version: v1.0.0        # Chart version (independent)
appVersion: v0.7.0   # Recommended operator version
```

### Image Tag Defaults

```yaml
# values.yaml
image:
  tag: ""  # Empty = defaults to Chart.AppVersion

# Template renders as:
image: "ghcr.io/nvidia/skyhook/operator:0.7.0"
```

### Image Pinning: Tag vs Digest

- You can specify either a tag or a digest for images.
- If both are provided, the **digest takes precedence** and determines the image pulled. The rendered image reference may display as `:tag@sha256:...`, but the digest controls selection.

## Release Branching Strategy

NodeWright uses **release branches** to manage patches and maintenance releases, in three families:

```bash
release/v0.19.x          # operator v0.19.* + chart v0.19.* (chart pins the agent it ships with)
release/v0.20.x          # operator v0.20.* + chart v0.20.*
release/agent/v7.0.x     # agent v7.0.* only; the chart picks it up through its agent pin
release/cli/v0.5.x       # cli v0.5.* only; installed by users, not shipped in the chart
```

### Why Release Branches:

- **Chart defines compatibility** - each `release/vX.Y.x` branch contains a tested, compatible set: the operator, the chart, and the agent version the chart pins
- **The agent releases on its own cadence** - `release/agent/vX.Y.x` carries only the agent, so an agent major (such as the v7 Go rewrite) neither forces an early operator minor nor ships as a chart patch
- **The CLI releases on its own cadence** - `release/cli/vX.Y.x` carries only the CLI, which users install and upgrade independently of the operator and which must keep working against older operators, so its versions do not line up with operator minors
- **Simplified patches** - fix bugs in the context of the full integrated system
- **Connected git history** - preserves relationships between operator, agent, and chart changes

### Branch Workflow:

1. **Main development** happens on `main` branch
2. **Operator release preparation** creates `release/v{MAJOR.MINOR}.x`; operator and chart RCs, finals and patches are tagged there
3. **Agent release preparation** creates `release/agent/v{MAJOR.MINOR}.x`; agent RCs, finals and patches are tagged there
4. **CLI release preparation** creates `release/cli/v{MAJOR.MINOR}.x`; CLI RCs, finals and patches are tagged there
5. **A new agent version reaches users** through a chart patch that bumps the agent pin in `chart/values.yaml` on the active `release/vX.Y.x`
6. **Critical fixes** may be backported from `main` to any kind of release branch

## Go Module Support

The operator supports Go module imports for external projects:

```bash
# External projects can import the operator
go get github.com/NVIDIA/nodewright/operator@v0.8.0
```

**Module mapping**: Tag `operator/v0.8.0` maps to module `github.com/NVIDIA/nodewright/operator@v0.8.0`

## Quick Reference

> These examples use `nodewright`, the default install namespace for new installs. Substitute your own if you installed elsewhere; installs predating the namespace rename are in `skyhook`.

```bash
# Check deployed versions
kubectl get deployment -n nodewright -o jsonpath='{.items[0].spec.template.spec.containers[0].image}'
helm list -n nodewright

# Override operator version
helm install skyhook ./chart --set controllerManager.manager.image.tag="0.8.0"

# Check release branches
git branch -r | grep release/
```

## Changelogs

Each component has a machine-generated `CHANGELOG.md` (regenerated from git history by `scripts/gen-changelog.sh`; do not hand-edit) and a human-authored `RELEASE_NOTES.md` for behavior changes and upgrade steps. See the "Changelogs and Release Notes" section of [release-process.md](../contributing/release-process.md) for the tooling and the generate-vs-curate split.

## Release Process

For step-by-step instructions on how to release components, see [release-process.md](../contributing/release-process.md).

**CI/CD triggers on git tags:**

- `operator/vx.y.z` → publishes operator image
- `agent/vx.y.z` → publishes agent image  
- `chart/vx.y.z` → publishes helm chart

**Chart versioning:**

- **PATCH**: Bug fixes, docs
- **MINOR**: New features, config options  
- **MAJOR**: Breaking changes to chart, or compatibility with agent or operator.