Skip to content

Versioning

VirtFoundry follows Semantic Versioning 2.0.0.

Pre-1.0

The project is not 1.0 yet. The current release line is 0.13.0.

Premature product tags v1.0.0–v1.5.0 and chart tags virtfoundry-1.x were cut too early and were deleted (2026-09-27) — they are not a SemVer 1.0 stability promise. Breaking changes may still land in 0.x MINOR bumps until a real 1.0.0 is declared.

The Helm index must not list 1.x packages; a bare helm install resolves 0.13.0. Pin anyway and install the CRDs first, then the operator:

helm install virtfoundry-crds virtfoundry/virtfoundry-crds --version 0.13.0 \
  -n virtfoundry-system --create-namespace
helm install virtfoundry-operator virtfoundry/virtfoundry-operator --version 0.13.0 \
  -n virtfoundry-system
helm install virtfoundry virtfoundry/virtfoundry --version 0.13.0 \
  -n virtfoundry-system \
  --set secrets.rootPassword='...' \
  --set secrets.jwtSecret='...'

Release units

Artifact Version source Tag Registry / URL
Application Git tag vX.Y.Z ghcr.io/virtfoundry/core, ui
Helm chart Chart.yaml version vX.Y.Z (same) https://virtfoundry.github.io/helm-charts
Operator Git tag vX.Y.Z ghcr.io/virtfoundry/operator
VKS operator + chart virtfoundry-vks Git tag (Chart.yaml matches) vX.Y.Z ghcr.io/virtfoundry/vks; chart from the virtfoundry/vks repo
Terraform provider Git tag (own line) vX.Y.Z Terraform Registry
VKS node image Kubernetes version node-ubuntu-* ghcr.io/virtfoundry/node-ubuntu:<k8s>@sha256:...
Documentation Built from chart repo main / tags — .../helm-charts/docs/

Chart.yaml appVersion matches the application release the chart defaults target.

Bump rules

Change Version bump Example
Bug fix, doc fix, security patch (non-breaking) PATCH 0.11.2 → 0.11.3
New feature, chart profile change MINOR 0.11.2 → 0.12.0
Breaking API or chart contract MINOR while on 0.x 0.11.2 → 0.12.0 (document in CHANGELOG)
First stable contract MAJOR 0.x → 1.0.0 (explicit declaration)

Release automation

scripts/release/release.sh does steps 2 to 5 below. Run it from a checkout of helm-charts that has the other repositories cloned next to it (core, operator, vks, .github):

DRY_RUN=1 VERBOSE=1 scripts/release/release.sh bump X.Y.Z "one line for core docs/PRODUCT.md"   # look first
scripts/release/release.sh bump X.Y.Z "one line for core docs/PRODUCT.md"   # opens one PR per repository
# merge the five PRs, one at a time, when CI is green
scripts/release/release.sh tag X.Y.Z   # tags core, operator, vks, helm-charts in order and waits for each

bump rewrites only known pin shapes (--version, chart version/appVersion, image tags, vX.Y.Z in commands, "current release" statements), moves the Unreleased changelog notes under a dated heading and adds the row to the compatibility table. Sentences about one specific release ("X.Y.Z and newer", "tested on X.Y.Z") are left as they are and printed under kept in <repo>: read that list and fix by hand what needs it. tag refuses to tag a repository whose main does not declare the version yet.

Not automated: the Terraform provider (own version line), the Terraform provider version in the compatibility table (copied from the previous row), merging the PRs, and the screenshots (step 7).

Release process

  1. Finish feature branch → PR → integration testing → merge main
  2. Update CHANGELOG.md (core, helm-charts, operator when touched)
  3. Bump every version pin (same X.Y.Z everywhere — do not skip UI, values, org landing, or GitHub Pages):
Repo Files
core ui/package.json, ui/package-lock.json (root + "packages" entry), docs/PRODUCT.md
helm-charts charts/virtfoundry/Chart.yaml, charts/virtfoundry-operator/Chart.yaml, charts/virtfoundry/values.yaml (images.api / images.ui), charts/virtfoundry-operator/values.yaml + values-homelab.yaml (image.tag), all install docs (quickstart, installation, kind, helm-repository, chart-values, index, README) — these feed GitHub Pages
vks charts/virtfoundry-vks/Chart.yaml (version, appVersion), CHANGELOG.md
terraform-provider CHANGELOG.md, version = "~> X.Y" in README and examples (own line, see below)
operator CHANGELOG.md only. Its chart lives in helm-charts (charts/virtfoundry-operator) and is bumped there
.github (org profile) profile/README.md — org homepage “Current release” + helm --version snippets (routinely forgotten)
This doc docs/project/versioning.md — current release line and examples

The UI sidebar/login label reads ui/package.json at build time (src/lib/version.ts). A chart bump without rebuilding/publishing UI leaves users on an old label (e.g. v0.5.0).

After merge to helm-charts main, confirm Pages shows the new badge/pins at https://virtfoundry.github.io/helm-charts/docs/ .

  1. Commit: chore(release): v0.13.0 Go one repository at a time. Each merge to main and each tag makes CI write a new image digest, so the cluster rolls that Deployment. Several rollouts at once can overload the node's CNI (Troubleshooting). After each merge and each tag, wait until the cluster has settled:
scripts/ops/wait-settled.sh   # NS, TIMEOUT and MIN_QUIET are configurable
  1. Tag each repository that changed:
git tag v0.13.0
git push origin v0.13.0
  1. CI publishes container images and Helm package; docs site rebuilds; homelab digest write-back updates Argo overlay
  2. After the homelab syncs, run the UI end-to-end, then refresh the docs screenshots. The UI end-to-end deploys a VM through the wizard, checks the post-deploy panel (IP, Copy ssh, console, Open VM) and deletes the VM:
pip install playwright && playwright install chromium
VF_PASSWORD=... python scripts/e2e/homelab-ui.py   # VF_USER, VF_UI_URL, VF_TEMPLATE, VF_SSH_KEY are optional

Then refresh the docs screenshots in a docs-only PR: python scripts/docs/capture-ui-shots.py writes docs/assets/screenshots/ in the dark theme (set VF_PASSWORD, and VF_USER and VF_UI_URL if they differ; the script has no default password). Check that the login footer shows the new version and that no secrets are visible.

Compatibility

VirtFoundry operator vks Terraform provider Node image (K8s)
0.13.0 0.13.0 0.13.0 0.4.1 node-ubuntu:1.36.5
0.12.0 0.12.0 0.12.0 0.4.1 node-ubuntu:1.36.5
0.11.3 0.11.3 0.11.3 0.4.1 node-ubuntu:1.36.5
0.11.2 0.11.2 0.11.2 0.4.0 node-ubuntu:1.36.5
0.11.1 0.11.1 0.11.1 0.4.0 node-ubuntu:1.36.5
0.11.0 0.11.0 0.11.0 0.4.0 node-ubuntu:1.36.5
0.10.0 0.10.0 0.10.0 0.4.0 node-ubuntu:1.36.5
0.9.0 0.9.0 — 0.3.1 —

The Terraform provider keeps its own 0.x line. It needs a VirtFoundry release that has the API it calls: virtfoundry_vks_cluster needs 0.10.0 or newer. The VKS chart and image share the product version from 0.10.0 on (earlier it was an untagged 0.1.0).

Consuming versions

# Helm — pin 0.13.0; CRDs first, then the operator (see Installation guide)
helm install virtfoundry-crds virtfoundry/virtfoundry-crds --version 0.13.0 ...
helm install virtfoundry-operator virtfoundry/virtfoundry-operator --version 0.13.0 ...
helm install virtfoundry virtfoundry/virtfoundry --version 0.13.0 \
  --set secrets.rootPassword='...' --set secrets.jwtSecret='...' ...

# Container images
ghcr.io/virtfoundry/core:0.13.0
ghcr.io/virtfoundry/ui:0.13.0
ghcr.io/virtfoundry/operator:0.13.0
ghcr.io/virtfoundry/vks:0.13.0

Tags latest (on main builds) may also exist — pin explicitly in production.

Cross-repo features

Use the same branch name in virtfoundry and helm-charts. Release with the same version number when both change.

Future: umbrella chart

0.10.x stays three charts and three Argo Applications. A later virtfoundry-platform umbrella (Helm dependencies + nested operator / core / vks values) is design-only — see Future platform umbrella chart.