Managing Chart Versions

1. Using Semantic Versioning

Version Component	Description	Example
Major	Breaking changes that require manual updates	`2.0.0`
Minor	Backward-compatible new features	`1.3.0`
Patch	Backward-compatible bug fixes	`1.2.4`

Example: Chart Version in `Chart.yaml`

apiVersion: v2
name: my-app
description: A Helm chart for my application
version: 2.1.3
appVersion: "1.2.4"

Note: Helm follows Semantic Versioning 2.0.0 to ensure compatibility and clear communication of changes.

2. Incrementing Chart Version

Version Field	Format	Description
version	`1.2.3`	Primary version number following semantic versioning (SemVer)
appVersion	`2.5.0`	Version of the application being deployed, not the chart itself

Example: Updating Chart Version

name: my-app
version: 2.1.0
appVersion: 3.0.0

Note: When incrementing the chart version, ensure that any dependencies or sub-charts are also updated if necessary.

3. Setting Application Version

Field	Description	Example
appVersion	Version of the application code	`"1.2.3"`

Example: Setting appVersion in Chart.yaml

apiVersion: v2
name: my-app
version: 1.0.0
appVersion: "1.2.3"

Note: The appVersion field is used to track the version of the application code, separate from the chart version.

4. Creating Version Constraints

Constraint Type	Format	Description	Example
Exact Version	`v1.2.3`	Matches exactly the specified version	`v1.2.3`
Compatible Range	`>=1.0.0 <2.0.0`	Matches any version within the range	`>=1.0.0 <2.0.0`
Wildcard	`1.x.x`	Matches any version in the major version	`1.x.x`
Caret Range	`^1.2.3`	Matches any version with same major and compatible minor/patch	`^1.2.3`
Tilde Range	`~1.2.3`	Matches any version with same major and compatible minor	`~1.2.3`

Example: Using Version Constraints in Chart Dependencies

dependencies:
- name: nginx
  version: "^1.20.0"
  repository: "https://kubernetes-charts.storage.googleapis.com"

Note: Version constraints in Helm charts help ensure compatibility and prevent unexpected behavior when updating dependencies.

5. Using Version Ranges

Range Type	Pattern	Description	Examples
Compatible	`~1.2.3`	Allows patch-level changes if the minor version is the same	`~1.2.3` matches `1.2.3`, `1.2.4`, but not `1.3.0`
Compatible	`~1.2`	Allows patch-level changes if the major and minor versions are the same	`~1.2` matches `1.2.0`, `1.2.1`, but not `1.3.0`
Compatible	`~1`	Allows patch-level changes if the major version is the same	`~1` matches `1.0.0`, `1.1.0`, but not `2.0.0`
Caret	`^1.2.3`	Allows changes that do not modify the left-most non-zero digit in the `MAJOR.MINOR.PATCH` version	`^1.2.3` matches `1.2.3`, `1.2.4`, `1.3.0`, but not `2.0.0`
Caret	`^0.2.3`	Allows changes that do not modify the left-most non-zero digit in the `MAJOR.MINOR.PATCH` version	`^0.2.3` matches `0.2.3`, `0.2.4`, but not `0.3.0`
Caret	`^0.0.3`	Allows changes that do not modify the left-most non-zero digit in the `MAJOR.MINOR.PATCH` version	`^0.0.3` matches `0.0.3`, but not `0.0.4`
Exact	`=1.2.3`	Matches exactly the specified version	`=1.2.3` matches only `1.2.3`
Greater Than	`>1.2.3`	Matches any version greater than the specified version	`>1.2.3` matches `1.2.4`, `1.3.0`, etc.
Less Than	`<1.2.3`	Matches any version less than the specified version	`<1.2.3` matches `1.2.2`, `1.1.0`, etc.
Range	`>=1.2.3 <2.0.0`	Matches any version within the specified range	`>=1.2.3 <2.0.0` matches `1.2.3`, `1.2.4`, ..., `1.9.9`

Example: Specifying Version Ranges in Chart Dependencies

dependencies:
- name: nginx
  version: ~1.2.0
  repository: https://kubernetes-charts.storage.googleapis.com/
- name: mysql
  version: ^2.0.0
  repository: https://charts.helm.sh/stable/

Note: Version ranges are used in requirements.yaml or Chart.yaml to specify compatible versions of dependencies.

Warning: Using ^0.0.x ranges can lead to unexpected behavior as minor versions are not stable.

6. Pinning Exact Versions

Property	Value	Description
version	`1.2.3`	Exact version string to pin
appVersion	`2.0.0`	Application version to pin

Example: Pinning Chart Version in requirements.yaml

dependencies:
- name: nginx
  version: 1.2.3
  repository: https://kubernetes-charts.storage.googleapis.com/

Example: Pinning Chart Version in values.yaml

nginx:
  image:
    tag: 1.2.3

Note: Pinning exact versions ensures reproducible deployments and prevents unexpected upgrades.

7. Using Tilde Range

The tilde range operator (~) in Helm is used to specify version constraints that allow patch-level updates while restricting minor and major version changes. It ensures backward compatibility by only permitting changes in the last digit of the version number.

Version Constraint	Description	Examples
~1.2.3	Allows patch-level updates (e.g., 1.2.4, 1.2.5) but not minor or major changes	Matches versions `1.2.3` to `1.3.0`
~1.2	Allows patch-level updates in the third digit, but not minor version changes	Matches versions `1.2.0` to `1.3.0`
~1	Allows updates in the second and third digits, but not major version changes	Matches versions `1.0.0` to `2.0.0`

Example: Tilde Range in Chart Dependencies

dependencies:
- name: nginx
  version: ~1.20.0
  repository: https://kubernetes-charts.storage.googleapis.com/

Note: The tilde range operator ensures that only patch-level updates are allowed, which is ideal for environments where stability and minimal risk of breaking changes are prioritized.

8. Using Caret Range

Version Specifier	Pattern	Description	Examples
^1.2.3	`^1.2.3`	Allows patch and minor updates, but not major version changes	`^1.2.3` matches `1.2.3`, `1.2.4`, `1.3.0`, but not `2.0.0`
^0.2.3	`^0.2.3`	Allows patch updates, but not minor or major version changes	`^0.2.3` matches `0.2.3`, `0.2.4`, but not `0.3.0` or `1.0.0`
^0.0.3	`^0.0.3`	Allows only patch updates	`^0.0.3` matches `0.0.3`, `0.0.4`, but not `0.0.5` or `0.1.0`

Example: Using Caret Range in Chart Dependencies

dependencies:
- name: nginx
  version: ^1.20.0
  repository: https://kubernetes-charts.storage.googleapis.com/

9. Maintaining Changelog

Field	Description	Example
name	Chart name	`my-app`
version	Chart version (semantic versioning)	`1.2.3`
appVersion	Application version	`2.4.0`
description	Short description of the chart	`A Helm chart for my application`
keywords	List of keywords for the chart	`["application", "helm"]`
home	Home page URL of the chart	`https://example.com`
sources	Source URLs for the chart	`["https://github.com/example/my-app"]`
maintainers	List of maintainers with name and email	`[{"name": "John Doe", "email": "john@example.com"}]`
icon	URL to an icon image	`https://example.com/icon.png`
apiVersion	API version of the chart (v1 or v2)	`v2`
engine	Template engine (default is gotpl)	`gotpl`
condition	Condition to enable the chart (optional)	`server.enabled`
tags	Tags for categorizing the chart	`["web", "frontend"]`
dependencies	List of chart dependencies	`[{"name": "mysql", "version": "8.0.0"}]`
annotations	Annotations for the chart	`{"helm.sh/chart": "my-app-1.2.3"}`

Example: Changelog Entry Format

# Changelog

## [1.2.3] - 2025-04-05
### Added
- New feature for user authentication
- Support for custom environment variables

### Changed
- Updated default image to v2.4.0
- Improved error handling in API calls

### Fixed
- Resolved issue with database connection timeout
- Fixed memory leak in logging module

## [1.2.2] - 2025-03-20
### Added
- Added support for TLS configuration

### Fixed
- Fixed bug in chart template rendering

Note: Changelog entries should follow semantic versioning principles and be updated with each new release.

Warning: Ensure that all changelog entries are consistent in format and accurately reflect changes made to the chart.

10. Tagging Chart Releases

Tag Format	Description	Example
chart.version	Version of the chart as defined in Chart.yaml	`1.2.3`
appVersion	Application version the chart deploys	`v1.2.3`
git.commit	Git commit hash of the chart source	`abc123de`

Example: Tagging Chart Release

helm package my-chart
git tag v1.2.3
git push origin v1.2.3

Note: Helm charts should be tagged with semantic versioning (SemVer) to indicate stability and compatibility.