fix(packaging): tilde-encode pre-release versions so RPM/DEB upgrades work (#588)

Releases rc.3 through rc.8 stripped the pre-release suffix (${VERSION%%-*}),
so every RC built the same NVR openwatch-0.2.0-1 — dnf reported the next RC as
'already installed' and never upgraded. The DEB used a hyphen revision
(0.2.0-rc.8), which orders RCs but sorts ABOVE 0.2.0, so GA would never
supersede an RC.

Encode pre-releases with a tilde instead (0.2.0~rc.8), which sorts below GA and
distinguishes RCs (verified via rpm.vercmp and dpkg --compare-versions). Add
Epoch 1 (RPM Epoch:, DEB 1: prefix) so an upgrade from the already-published
bare-0.2.0 installs is not seen as a downgrade — proven in a rockylinux:9
container: the published rc.7 (0:0.2.0-1) upgrades cleanly to 1:0.2.0~rc.8-1.
Build the binary with the full semver so 'openwatch --version' still reports
0.2.0-rc.8.

Spec release-package-build v1.1.0 (C-12/AC-21) + a source-inspection regression
test. Install-guide examples updated to the tilde filenames.

Author: remyluslosius

docs/engineering/install_guide.md

@@ -99,7 +99,7 @@ PGPASSWORD='replace-with-a-strong-password' \
 ### Step 3 — Install the packages
 
 ```bash
-sudo dnf install -y ./openwatch-0.2.0-1.x86_64.rpm ./kensa-rules-0.4.3-1.noarch.rpm
+sudo dnf install -y ./openwatch-0.2.0~rc.8-1.x86_64.rpm ./kensa-rules-0.4.3-1.noarch.rpm
 ```
 
 Install **both** files in one transaction. `openwatch` declares a hard
@@ -247,7 +247,7 @@ PGPASSWORD='replace-with-a-strong-password' \
 ### Step 3 — Install the packages
 
 ```bash
-sudo apt install -y ./openwatch_0.2.0-rc.8_amd64.deb ./kensa-rules_0.4.3_all.deb
+sudo apt install -y ./openwatch_0.2.0~rc.8_amd64.deb ./kensa-rules_0.4.3_all.deb
 ```
 
 Install **both** files together — `openwatch` `Depends` on `kensa-rules` (the

packaging/deb/build-deb.sh

@@ -25,8 +25,15 @@ if [ -z "${VERSION:-}" ]; then
         VERSION="0.1.0"
     fi
 fi
-# DEB allows hyphens; reuse upstream version as-is.
-DEB_VERSION="$VERSION"
+# Pre-release ordering: DEB (like RPM) needs '~' to sort a pre-release BELOW
+# the final release (0.2.0~rc.8 < 0.2.0). A plain hyphen revision (0.2.0-rc.8)
+# sorts ABOVE 0.2.0, so GA would never supersede an RC. Epoch 1 steps over the
+# rc.3..rc.8 .debs already published with the hyphen form. The control file
+# carries the epoch; the .deb filename omits it (Debian convention). The binary
+# keeps the true semver ($VERSION, e.g. 0.2.0-rc.8).
+DEB_EPOCH="${DEB_EPOCH:-1}"
+DEB_UPSTREAM="${VERSION/-/\~}"                 # 0.2.0-rc.8 -> 0.2.0~rc.8 (GA unchanged)
+DEB_VERSION="${DEB_EPOCH}:${DEB_UPSTREAM}"     # control Version field (e.g. 1:0.2.0~rc.8)
 # Target architecture (Debian names, which match GOARCH for our targets).
 ARCH="${ARCH:-amd64}"
 case "$ARCH" in
@@ -40,8 +47,8 @@ mkdir -p "$DIST_DIR"
 # Step 1: build the Go binary for the target arch. CGO is disabled so the
 # binary is portable and cross-compiles without a C toolchain (the embedded
 # frontend SPA is arch-independent).
-echo ">> building openwatch binary (version=${DEB_VERSION}, arch=${ARCH})"
-GOOS=linux GOARCH="$ARCH" CGO_ENABLED=0 make build VERSION="$DEB_VERSION" >/dev/null
+echo ">> building openwatch binary (version=${VERSION}, arch=${ARCH})"
+GOOS=linux GOARCH="$ARCH" CGO_ENABLED=0 make build VERSION="$VERSION" >/dev/null
 
 # Step 2: stage the package tree.
 STAGE="$(mktemp -d)"
@@ -90,6 +97,6 @@ install -m 0755 "$APP_DIR/packaging/deb/postrm"    "$STAGE/DEBIAN/postrm"
 
 # Step 4: dpkg-deb.
 echo ">> running dpkg-deb"
-OUT="$DIST_DIR/openwatch_${DEB_VERSION}_${ARCH}.deb"
+OUT="$DIST_DIR/openwatch_${DEB_UPSTREAM}_${ARCH}.deb"
 dpkg-deb --root-owner-group --build "$STAGE" "$OUT" >/dev/null
 echo ">> wrote $(basename "$OUT") to $DIST_DIR/"

packaging/rpm/build-rpm.sh

@@ -26,8 +26,14 @@ if [ -z "${VERSION:-}" ]; then
         VERSION="0.1.0"
     fi
 fi
-# Strip any -dev / -alpha / -rc suffixes — RPM version field doesn't allow them.
-RPM_VERSION="${VERSION%%-*}"
+# RPM versions cannot contain '-', so encode a pre-release suffix with '~'
+# (tilde), which RPM sorts BELOW the final release and orders RCs correctly:
+#   0.2.0~rc.7  <  0.2.0~rc.8  <  0.2.0   (GA)
+# A bare GA version (no '-') is left unchanged. Do NOT strip the suffix — that
+# collapsed every RC to the same NVR (openwatch-0.2.0-1), so dnf saw rc.8 as
+# already installed. The spec carries Epoch:1 to step over those earlier
+# bare-0.2.0 RCs on upgrade.
+RPM_VERSION="${VERSION/-/\~}"
 RPM_RELEASE="${RPM_RELEASE:-1}"
 DIST_DIR="${APP_DIR}/dist"
 
@@ -45,8 +51,10 @@ mkdir -p "$DIST_DIR"
 # outside rpmbuild's %build so the chroot needs no Go toolchain. CGO is
 # disabled for a portable binary that cross-compiles without a C toolchain
 # (the embedded frontend SPA is arch-independent).
-echo ">> building openwatch binary (version=${RPM_VERSION}, arch=${RPM_ARCH})"
-GOOS=linux GOARCH="$GOARCH" CGO_ENABLED=0 make build VERSION="$RPM_VERSION" >/dev/null
+# Build the binary with the FULL version (e.g. 0.2.0-rc.8) so `openwatch
+# --version` reports the real pre-release, not the tilde-encoded RPM form.
+echo ">> building openwatch binary (version=${VERSION}, arch=${RPM_ARCH})"
+GOOS=linux GOARCH="$GOARCH" CGO_ENABLED=0 make build VERSION="$VERSION" >/dev/null
 
 # Step 2: stage the rpmbuild tree.
 RPMTOP="$(mktemp -d)"

packaging/rpm/openwatch.spec

@@ -18,6 +18,14 @@
 %{!?ow_release: %global ow_release 1}
 
 Name:           openwatch
+# Epoch 1 is a permanent, deliberate bump. Releases rc.3 through rc.8 shipped
+# with the pre-release suffix stripped, so they all carried the NVR
+# openwatch-0.2.0-1 (Epoch 0). The build now encodes pre-releases with a tilde
+# (0.2.0~rc.N, which sorts below GA 0.2.0), but 0.2.0~rc.N < 0.2.0 would read as
+# a DOWNGRADE from those mis-versioned installs. Epoch 1 sorts strictly above
+# Epoch 0, so `dnf upgrade` cleanly moves a bare-0.2.0 install onto the
+# correctly-versioned packages. Epoch is sticky: never lower it.
+Epoch:          1
 Version:        %{ow_version}
 Release:        %{ow_release}%{?dist}
 Summary:        OpenWatch Compliance Platform (Go binary)

packaging/tests/package_test.go

@@ -650,3 +650,52 @@ func sizeOr(info os.FileInfo) int64 {
 
 // Verify there's no spurious error import.
 var _ = errors.New
+
+// @ac AC-21
+// AC-21: pre-release versions are tilde-encoded with Epoch 1 across both
+// packages, and the binary keeps the true semver. Source-inspection backstop
+// for the rc.3..rc.8 regression where the suffix was stripped, collapsing
+// every RC to the same NVR (openwatch-0.2.0-1) so dnf saw the next RC as
+// already installed.
+func TestPackaging_PreReleaseVersioning(t *testing.T) {
+	t.Run("release-package-build/AC-21", func(t *testing.T) {
+		dir := appDir(t)
+		read := func(rel string) string {
+			b, err := os.ReadFile(filepath.Join(dir, rel))
+			if err != nil {
+				t.Fatalf("read %s: %v", rel, err)
+			}
+			return string(b)
+		}
+		rpmBuild := read("packaging/rpm/build-rpm.sh")
+		spec := read("packaging/rpm/openwatch.spec")
+		debBuild := read("packaging/deb/build-deb.sh")
+
+		// The stripping bug must be gone, replaced by a tilde conversion.
+		if strings.Contains(rpmBuild, "${VERSION%%-*}") {
+			t.Error("build-rpm.sh still strips the pre-release suffix (${VERSION%%-*}); use a tilde instead")
+		}
+		if !strings.Contains(rpmBuild, `${VERSION/-/\~}`) {
+			t.Error("build-rpm.sh must tilde-encode the version (${VERSION/-/\\~})")
+		}
+		// RPM spec carries Epoch.
+		if !regexp.MustCompile(`(?m)^Epoch:\s*1\b`).MatchString(spec) {
+			t.Error("openwatch.spec must declare 'Epoch: 1'")
+		}
+		// DEB: tilde upstream + epoch prefix in the control version.
+		if !strings.Contains(debBuild, `${VERSION/-/\~}`) {
+			t.Error("build-deb.sh must tilde-encode the upstream version")
+		}
+		if !strings.Contains(debBuild, "DEB_EPOCH") || !strings.Contains(debBuild, `${DEB_EPOCH}:${DEB_UPSTREAM}`) {
+			t.Error("build-deb.sh must prefix the control version with the epoch (1:upstream)")
+		}
+		// Both scripts build the binary with the FULL semver, not the
+		// tilde/stripped package version.
+		if !strings.Contains(rpmBuild, `make build VERSION="$VERSION"`) {
+			t.Error("build-rpm.sh must build the binary with the full $VERSION (true semver)")
+		}
+		if !strings.Contains(debBuild, `make build VERSION="$VERSION"`) {
+			t.Error("build-deb.sh must build the binary with the full $VERSION (true semver)")
+		}
+	})
+}

specs/release/package-build.spec.yaml

@@ -1,7 +1,7 @@
 spec:
   id: release-package-build
   title: Native RPM and DEB packaging
-  version: "1.0.0"
+  version: "1.1.0"
   status: approved
   tier: 2
 
@@ -106,6 +106,22 @@ spec:
         per install). openssl MUST be a package dependency.
       type: security
       enforcement: error
+    - id: C-12
+      description: >
+        A pre-release VERSION (one carrying a hyphen suffix such as
+        0.2.0-rc.8) MUST be encoded in both packages with a tilde, never by
+        stripping the suffix: the RPM Version and the DEB upstream version MUST
+        be 0.2.0~rc.8. The tilde sorts a pre-release BELOW the final release
+        (0.2.0~rc.8 < 0.2.0) so GA cleanly supersedes it, and distinguishes RCs
+        from each other (stripping collapsed every RC to the same NVR, so dnf
+        reported the next RC as already installed). Because releases rc.3..rc.8
+        shipped with the suffix stripped (bare 0.2.0, Epoch 0 / no epoch), both
+        packages MUST carry Epoch 1 (RPM Epoch:, DEB version prefix 1:) so an
+        upgrade from those mis-versioned installs is not seen as a downgrade.
+        The embedded binary MUST still report the true semver (0.2.0-rc.8), not
+        the tilde form. Source-inspection enforces (AC-21).
+      type: technical
+      enforcement: error
 
   acceptance_criteria:
     - id: AC-01
@@ -186,3 +202,14 @@ spec:
       description: The package payloads ship the empty /etc/openwatch/keys directory and the provisioning helper at /usr/lib/openwatch/, but do NOT contain jwt_private.pem or credential.key (verified via rpm -qpl and dpkg-deb -c — the keys are generated per-install, never packaged).
       priority: critical
       references_constraints: [C-11]
+    - id: AC-21
+      description: >-
+        Source-inspection of the build scripts and RPM spec — build-rpm.sh
+        encodes the version with a tilde (it must NOT strip the suffix via the
+        bash %%- expansion), openwatch.spec declares Epoch 1, build-deb.sh
+        prefixes the DEB control version with the epoch-1 form and tilde-encodes
+        the upstream version, and both scripts build the binary with the full
+        semver $VERSION (not the tilde/stripped form). Backstops the rc.3..rc.8
+        NVR-collision regression.
+      priority: critical
+      references_constraints: [C-12]