> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cnap.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Package Versioning

> How CNAP manages package versions and updates for your deployments

CNAP automatically manages versioning for all generated packages. Every template update creates a new package version, giving you complete control over deployments and the ability to track changes over time.

## How Versioning Works

CNAP uses <Tooltip headline="Semantic Versioning" tip="Semantic versioning is a versioning scheme using three numbers (major.minor.patch) like 1.2.3. The major number indicates breaking changes, minor indicates new features, and patch indicates bug fixes. This helps track changes and manage compatibility.">semantic versioning</Tooltip> (major.minor.patch) for all packages:

* **First version** - New templates start at `0.1.0`
* **Automatic updates** - Patch version increments when you update a template (e.g., `0.1.0` → `0.1.1`)
* **Version history** - All versions are tracked and remain available

### Version Format

Semantic versions use three numbers: **major.minor.patch** (e.g., `0.1.0`). Currently, CNAP increments the patch version when templates are updated. Major and minor version bumps are planned for future releases.

## Why Versioning Matters

Versioning gives you control and confidence in your deployments:

### Track Changes

Every template update creates a new version, so you can see exactly what changed and when. This helps with debugging, compliance, and understanding your deployment history.

### Safe Updates

New installs use the latest version by default, but existing installs continue using their current version. This prevents unexpected changes and lets you update on your schedule.

### Rollback Capability

If something goes wrong with a new version, you can rollback to any previous version instantly. All versions remain available for deployment.

### Gradual Rollouts

You can test new versions on specific installs before rolling out to everyone. This lets you validate changes in production without risking all your deployments.

## Managing Versions

### Viewing Versions

All package versions for a template are tracked and available. You can see:

* Version numbers (e.g., `0.1.0`, `0.1.1`)
* When each version was created
* Which installs are using which versions

### Using Versions

When deploying, you can:

* **Use latest** - Automatically deploy the most recent version
* **Pin to specific version** - Lock an install to a particular version for stability
* **Rollback** - Switch an install to a previous version if needed

### Updating Templates

When you update a template:

1. **You modify sources** - Change Helm charts, values, or manifests
2. **New version generated** - CNAP creates a new package version automatically
3. **Version incremented** - Patch version increases (e.g., `0.1.0` → `0.1.1`)
4. **New installs use latest** - Fresh deployments automatically use the new version
5. **Existing installs unchanged** - Current deployments continue using their version

<Warning>
  Existing installs don't automatically update to new versions. You must explicitly update them if you want them to use a newer package version.
</Warning>

## Version Best Practices

### For Stability

* **Pin critical installs** - Lock production deployments to specific versions
* **Test before rollout** - Deploy new versions to staging first
* **Monitor changes** - Review what changed between versions
* **Plan updates** - Schedule version updates during low-traffic periods

### For Development

* **Track versions** - Keep notes on what changed in each version
* **Test locally** - Download and test packages before deploying
* **Use version history** - Compare packages between versions
* **Automate testing** - Test new versions in your CI/CD pipeline

## Related Topics

* [Package Generation →](/charts/chart-generation) - Learn how packages are generated
* [Templates Guide →](/products/templates) - Understand templates
* [Create a Product →](/products) - See versioning in action