Decide what a version number means for each artifact class

[cshuttle]

Part of #25

Question

What does a version number mean for each class of artifact this map covers, and is it the same scheme everywhere?

Three classes behave differently:

• Container images (Topology, Atlas, VirtualWindow, eventually nmon) — deployed continuously today; a human rarely reads the version.
• Reusable workflows (cshuttle/workflows) — consumed by reference from other repos, so the tag is an API surface others pin to. A floating major (v1) is the GitHub-ecosystem convention.
• Compiled binaries (chrome-exporter) — downloaded and installed onto hosts; the version is what answers "which build is on LaundryRoomDisplay?"

Decide: semver, CalVer, or per-class schemes; what bumps a major in a homelab with one operator; and whether a floating major tag exists alongside exact versions.

This gates the release workflow and every repo-level ticket.

[cshuttle]

Resolution

One shape, three meanings. Every artifact on this map is tagged vMAJOR.MINOR.PATCH; what the number claims differs by class.

Class	Repos	The version is	A major means
Reusable workflows	cshuttle/workflows	a compatibility contract — other repos' CI breaks if it's wrong	consumers must edit their uses: line
Apps	Topology, Atlas, VirtualWindow, nmon	a rollback anchor + identifier — no compat claim to anyone	the deploy needs a human step
Binaries	Monitoring/chrome-exporter	an identifier — "which build is on that host?"	(same deploy-needs-a-hand test)

The rules

• Shape: semver everywhere, meaning varies. CalVer was rejected: v2026.08.02 is not valid semver (leading zeros are forbidden), which would break argocd-image-updater's semver strategy and Renovate's version detection; a monotonic counter was rejected for the same tool-friendliness reason. One shape means no per-repo tool config.
• Major, for the app and binary classes — the release cannot go out by the normal automated path alone. Concretely: a volume or data migration, a new/renamed env var or secret, a hostname/route/port change, or a required manifest/compose edit. The test is "does this deploy clean on its own?" — deliberately answerable, so the number doesn't decay into permanent patch bumps.
• Minor — a capability someone would notice. Patch — everything else (fixes, dependency bumps, chores).
• No floating major tag. cshuttle/workflows publishes immutable exact tags only; consumers pin @v1.2.0, and Renovate carries each bump as a reviewable per-repo PR. The GitHub-ecosystem moving-v1 convention was rejected because it contradicts the estate's own reason for helpers:pinGitHubActionDigests — a moved tag changes ~8 repos' CI with no diff, no PR, and no record of which consumer ran which code. Accepted cost: PR volume per release.
• chrome-exporter is tagged chrome-exporter/vX.Y.Z inside cshuttle/Monitoring, matching Go's subdirectory-module convention (it declares its own module chrome_exporter). Keeps Monitoring's config side — netdata configs, dashboards, health checks, explicitly Out of scope on the map — unversioned. Splitting it into its own repo (the nmon precedent from 2026-07-16) was considered and rejected as scope creep.
• First tag is v1.0.0 for workflows, Topology, Atlas, nmon and chrome-exporter/. All are running in production daily, so 0.x would be a fiction. VirtualWindow already sits at v1.0.0; its next number is decided in its own ticket under the major rule above.

Consequences for other tickets

• Release-cut mechanism — the major rule is a human judgement about deployability, so a purely commit-derived bot cannot evaluate it. Any release-bot option must leave the major call to the operator.
• Shared release workflow — must support a tag-prefix trigger (chrome-exporter/v*), not just v*, and must not create or move a floating tag.
• Pinning consumers — exact pins rot without automation, so Renovate coverage of uses: refs is part of that ticket, not an afterthought.
• The write-up — this constrains future work, so it earns an ADR under the estate's own standard; it lands with the shared release workflow rather than as a separate ticket.