Give beta DEB and RPM packages a pre-release number (#113) (#116)

* build: give beta DEB and RPM packages a pre-release number (#113)

composePackageVersion is the package version of every Compose target
format, so an RPM or DEB built from a beta tag carried exactly the
version of the following stable one. dnf, rpm -U and dpkg refuse to
replace a package by one of equal version, so a beta user could not
move to the stable.

Keep the version and tell the packages apart by the package release
number, following the Fedora pre-release convention: the new Gradle
property linuxAppRelease is passed to jpackage as --linux-app-release
(Compose LinuxPlatformSettings.appRelease) and defaults to 1.

  beta-v1.50.0-beta-001 -> 1.50.0-0.beta.001
  beta-v1.50.0-rc02     -> 1.50.0-0.rc02
  v1.50.0               -> 1.50.0-1

Everything starting with "0." sorts below "1" for both rpm and dpkg.
Nightlies and local builds do not set the property and keep release 1.

Fixes #113

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* ci: derive the Linux release number from the tag and verify the tag version (#113)

The DEB and RPM jobs now compute the package release from the tag
before calling Gradle and pass it as -PlinuxAppRelease: a stable
vX.Y.Z tag gives 1, a beta-vX.Y.Z-<suffix> tag gives 0.<suffix> with
"-" turned into ".". The result must match [A-Za-z0-9.]+, otherwise
the step fails. A workflow_dispatch run from a branch keeps release 1
like the nightlies; nightly-artifacts.yml is unchanged.

The test job, which every packaging job depends on, now checks right
after the checkout that the X.Y.Z in the tag equals
composePackageVersion in gradle.properties and fails with a clear
message otherwise, so a mistagged commit fails before an hour of
packaging rather than shipping packages whose version contradicts
their file name and upgrade order.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: describe the pre-release number of beta DEB and RPM packages (#113)

The German and English installation manuals say in the Debian/Ubuntu
and Fedora sections that beta packages carry a pre-release number
below the stable one, so the stable installs as an upgrade over a
beta. The v1.50 changelogs gain the matching "Fixed" entry, and
PROJECT_CONTEXT.md records the rule next to the MSI decision.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

.github/workflows/tagged-release.yml

@@ -19,7 +19,8 @@ jobs:
   # Same job as in pr-compile-check.yml, copied rather than shared: a reusable workflow
   # would be one more indirection to read, and the comments belong next to the steps they
   # explain. Every packaging job below needs this one, so a commit whose tests fail builds
-  # no artifact (#62). Edit all three copies together.
+  # no artifact (#62). Edit all three copies together -- except for the tag check
+  # right after the checkout, which only makes sense here.
   test:
     name: Test (Java 21, headless)
     runs-on: ubuntu-latest
@@ -28,6 +29,33 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v7
 
+      # composePackageVersion is the package version of every Compose target format,
+      # and the Linux package release below is derived from the tag alone. A tag that
+      # names a different X.Y.Z than gradle.properties would therefore ship packages
+      # whose version contradicts their file name and upgrade order (#113). Fail
+      # before the tests rather than after an hour of packaging. Skipped for
+      # workflow_dispatch, where the ref is a branch and carries no version.
+      - name: Verify the tag matches composePackageVersion
+        if: github.ref_type == 'tag'
+        env:
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          if [[ "$REF_NAME" =~ ^v([0-9]+\.[0-9]+\.[0-9]+)$ ]]; then
+            TAG_VERSION="${BASH_REMATCH[1]}"
+          elif [[ "$REF_NAME" =~ ^beta-v([0-9]+\.[0-9]+\.[0-9]+)-.+$ ]]; then
+            TAG_VERSION="${BASH_REMATCH[1]}"
+          else
+            echo "::error::Tag '$REF_NAME' is neither vX.Y.Z nor beta-vX.Y.Z-<suffix>, so it carries no package version"
+            exit 1
+          fi
+          PROPERTY_VERSION="$(sed -n 's/^composePackageVersion=//p' gradle.properties)"
+          if [[ "$TAG_VERSION" != "$PROPERTY_VERSION" ]]; then
+            echo "::error::Tag $REF_NAME names version $TAG_VERSION, but gradle.properties has composePackageVersion=$PROPERTY_VERSION. Bump composePackageVersion (and version) before tagging, or move the tag."
+            exit 1
+          fi
+          echo "Tag $REF_NAME matches composePackageVersion=$PROPERTY_VERSION"
+
       - name: Set up Java 21
         uses: actions/setup-java@v6.0.1
         with:
@@ -269,9 +297,41 @@ jobs:
       - name: Ensure gradlew is executable
         run: chmod +x gradlew
 
+      # rpm and dpkg refuse to replace a package by one of equal version, and the
+      # version is composePackageVersion for beta and stable alike. The package
+      # RELEASE number tells them apart, following the Fedora pre-release convention:
+      #   beta-v1.50.0-beta-001 -> 1.50.0-0.beta.001, beta-v1.50.0-rc02 -> 1.50.0-0.rc02,
+      #   v1.50.0 -> 1.50.0-1. Everything starting with "0." sorts below "1", so the
+      # stable installs as an upgrade over any beta (#113). The beta part is the tag
+      # remainder after beta-vX.Y.Z- with "-" turned into "."; rpm and dpkg accept
+      # only [A-Za-z0-9.] there, anything else fails this step. nightly-artifacts.yml
+      # does not set the property and keeps release 1, as do local builds.
+      - name: Derive the Linux package release from the tag
+        env:
+          REF_NAME: ${{ github.ref_name }}
+          REF_TYPE: ${{ github.ref_type }}
+        run: |
+          set -euo pipefail
+          if [[ "$REF_TYPE" != "tag" ]]; then
+            RELEASE="1"
+          elif [[ "$REF_NAME" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            RELEASE="1"
+          elif [[ "$REF_NAME" =~ ^beta-v[0-9]+\.[0-9]+\.[0-9]+-(.+)$ ]]; then
+            RELEASE="0.${BASH_REMATCH[1]//-/.}"
+          else
+            echo "::error::Tag '$REF_NAME' is neither vX.Y.Z nor beta-vX.Y.Z-<suffix>, so no package release can be derived"
+            exit 1
+          fi
+          if [[ ! "$RELEASE" =~ ^[A-Za-z0-9.]+$ ]]; then
+            echo "::error::Derived package release '$RELEASE' contains characters rpm and dpkg do not accept"
+            exit 1
+          fi
+          echo "Linux package release for $REF_NAME: $RELEASE"
+          echo "LINUX_APP_RELEASE=$RELEASE" >> "$GITHUB_ENV"
+
       - name: Build Debian package
         run: |
-          ./gradlew -S :app-desktop:packageDeb
+          ./gradlew -S :app-desktop:packageDeb -PlinuxAppRelease="$LINUX_APP_RELEASE"
           mkdir -p dist
           DEB="$(ls app-desktop/build/compose/binaries/main/deb/*.deb | head -n 1)"
           if [ -z "$DEB" ]; then
@@ -308,9 +368,41 @@ jobs:
       - name: Ensure gradlew is executable
         run: chmod +x gradlew
 
+      # rpm and dpkg refuse to replace a package by one of equal version, and the
+      # version is composePackageVersion for beta and stable alike. The package
+      # RELEASE number tells them apart, following the Fedora pre-release convention:
+      #   beta-v1.50.0-beta-001 -> 1.50.0-0.beta.001, beta-v1.50.0-rc02 -> 1.50.0-0.rc02,
+      #   v1.50.0 -> 1.50.0-1. Everything starting with "0." sorts below "1", so the
+      # stable installs as an upgrade over any beta (#113). The beta part is the tag
+      # remainder after beta-vX.Y.Z- with "-" turned into "."; rpm and dpkg accept
+      # only [A-Za-z0-9.] there, anything else fails this step. nightly-artifacts.yml
+      # does not set the property and keeps release 1, as do local builds.
+      - name: Derive the Linux package release from the tag
+        env:
+          REF_NAME: ${{ github.ref_name }}
+          REF_TYPE: ${{ github.ref_type }}
+        run: |
+          set -euo pipefail
+          if [[ "$REF_TYPE" != "tag" ]]; then
+            RELEASE="1"
+          elif [[ "$REF_NAME" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            RELEASE="1"
+          elif [[ "$REF_NAME" =~ ^beta-v[0-9]+\.[0-9]+\.[0-9]+-(.+)$ ]]; then
+            RELEASE="0.${BASH_REMATCH[1]//-/.}"
+          else
+            echo "::error::Tag '$REF_NAME' is neither vX.Y.Z nor beta-vX.Y.Z-<suffix>, so no package release can be derived"
+            exit 1
+          fi
+          if [[ ! "$RELEASE" =~ ^[A-Za-z0-9.]+$ ]]; then
+            echo "::error::Derived package release '$RELEASE' contains characters rpm and dpkg do not accept"
+            exit 1
+          fi
+          echo "Linux package release for $REF_NAME: $RELEASE"
+          echo "LINUX_APP_RELEASE=$RELEASE" >> "$GITHUB_ENV"
+
       - name: Build Fedora package
         run: |
-          ./gradlew -S :app-desktop:packageRpm
+          ./gradlew -S :app-desktop:packageRpm -PlinuxAppRelease="$LINUX_APP_RELEASE"
           mkdir -p dist
           RPM="$(ls app-desktop/build/compose/binaries/main/rpm/*.rpm | head -n 1)"
           if [ -z "$RPM" ]; then

app-desktop/build.gradle.kts

@@ -143,7 +143,28 @@ compose.desktop {
                 "jdk.xml.dom", "jdk.unsupported",
             )
 
-            linux { iconFile.set(rootProject.file("packaging/icons/kst4contest.png")) }
+            linux {
+                iconFile.set(rootProject.file("packaging/icons/kst4contest.png"))
+                /*
+                 * Package release number behind the version (1.50.0-<release>).
+                 * The version itself is composePackageVersion for every target
+                 * format, so a beta DEB/RPM would otherwise carry exactly the
+                 * version of the following stable one -- and dnf, rpm -U and
+                 * dpkg refuse to replace a package by one of equal version, so
+                 * a beta user could not move to the stable (#113). The tagged
+                 * release workflow therefore passes -PlinuxAppRelease following
+                 * the Fedora pre-release convention:
+                 *
+                 *   beta-v1.50.0-beta-001  ->  1.50.0-0.beta.001
+                 *   beta-v1.50.0-rc02      ->  1.50.0-0.rc02
+                 *   v1.50.0                ->  1.50.0-1
+                 *
+                 * Everything starting with "0." sorts below "1" for both rpm
+                 * and dpkg. Nightlies and local builds do not set the property
+                 * and keep release 1.
+                 */
+                appRelease = providers.gradleProperty("linuxAppRelease").orElse("1").get()
+            }
             windows {
                 iconFile.set(rootProject.file("packaging/icons/kst4contest.ico"))
                 /*

docs/PROJECT_CONTEXT.md

@@ -226,6 +226,7 @@ Current website/deployment scripts and update-feed behaviour must be inspected b
 - `APPLICATION_CURRENT_VERSION` is the user-visible semantic version and must use the dotted `major.minor.patch` form. `APPLICATION_CURRENTVERSIONNUMBER` is retained only for older feeds and encodes patch releases by appending the patch digit, for example `1.43.1` as `1.431`.
 - The tagged-release workflow creates the GitHub Release before building the website update feed. This ordering is required because `versionInfo.js` reads the published release body through the GitHub Releases API.
 - Stable tags ship a Windows MSI installer (`KST4Contest-<tag>-windows-x64.msi`, Compose `packageMsi`, jpackage with WiX 3) next to the unchanged portable ZIP (issue #61). It installs per user without UAC and carries the fixed `upgradeUuid` in `app-desktop/build.gradle.kts`, which must never change because Windows Installer uses it to replace the installed version. Nightlies and beta tags stay ZIP-only: an MSI always carries `composePackageVersion`, so a nightly or beta MSI would have the same version as the following stable one, and jpackage's upgrade table only accepts strictly higher versions, so Windows Installer would refuse the stable over an installed beta. Installed and portable copies share `~/.praktiKST`. The website download data (`downloads.js`, `beta.js`) lists the MSI only when the release actually has that asset.
+- Beta DEB and RPM packages keep `composePackageVersion` but carry the Fedora pre-release number `0.<suffix>` as package release (`beta-v1.50.0-beta-001` -> `1.50.0-0.beta.001`, `beta-v1.50.0-rc02` -> `1.50.0-0.rc02`, stable `v1.50.0` -> `1.50.0-1`), passed as `-PlinuxAppRelease` by the tagged-release workflow, because rpm and dpkg refuse an equal version and a beta user could otherwise not move to the stable (issue #113); nightlies and local builds keep release 1, and the test job fails a tag whose `X.Y.Z` differs from `composePackageVersion`.
 - After publication, the workflow tests and builds the website, validates the expected Stable version, attaches `kst4ContestVersionInfo.xml` to the release and uploads the complete website build as a workflow artifact.
 
 ### Server-side website statistics

github_docs/de-Changelog.md

@@ -46,6 +46,7 @@ Mehrere Operateure an einem Rechner können jetzt eigene Rufzeichen, Locators un
 - **Keine automatischen Cluster-Spots für gearbeitete Stationen:** Der lokale DX-Cluster-Server erzeugte Spots aus Richtungsgelegenheiten, ohne den Worked-Status zu prüfen. Jetzt wird kein Spot mehr erzeugt, wenn die Station auf dem Band der erkannten Frequenz bereits gearbeitet ist; ohne bandbezogene Information zählt der allgemeine Worked-Status. Manuelle Spots aus der Karte und der Test-Spot in den Einstellungen bleiben unverändert. Damit ist [Issue #91](https://github.com/praktimarc/kst4contest/issues/91) behoben.
 - **QSO-Monitoring übernimmt keine Fremdeinträge mehr:** Die `preferences.xml` enthielt neben der Liste der überwachten Rufzeichen eine zweite Liste `snifferWords`, die nirgends in der Oberfläche erschien. Beim Laden wurden ihre Einträge trotzdem als Rufzeichen in das QSO-Monitoring übernommen. Die tote Liste ist entfernt; ein vorhandenes `snifferWords`-Element in alten Dateien wird ignoriert. Damit ist [Issue #103](https://github.com/praktimarc/kst4contest/issues/103) behoben.
 - **Kein Locator für die zweite Kategorie mehr:** Intern gab es eine Einstellung für einen eigenen Locator der zweiten Chat-Kategorie, die weder in der Oberfläche noch in der `preferences.xml` erschien und deshalb immer auf ihrem eingebauten Standardwert stand. Beim Verbindungsaufbau wurde dieser Standardwert mit dem eigenen Locator verglichen und eine Warnung ausgegeben, dass der zweite Locator ignoriert werde. ON4KST verwendet ohnehin einen Locator pro TCP-Sitzung; die Einstellung und die Warnung sind entfernt. Damit ist [Issue #104](https://github.com/praktimarc/kst4contest/issues/104) behoben.
+- **Linux-Beta-Pakete lassen sich auf das stabile Paket aktualisieren:** DEB- und RPM-Pakete eines Beta-Tags trugen dieselbe Versionsnummer wie das folgende stabile Paket, sodass `dnf` und `dpkg` die Aktualisierung als gleiche Version ablehnten. Beta-Pakete erhalten jetzt eine Vorab-Release-Nummer (`1.50.0-0.beta.001`) unter der des stabilen Pakets (`1.50.0-1`), und der Release-Lauf bricht ab, wenn der Tag nicht zur `composePackageVersion` passt. Damit ist [Issue #113](https://github.com/praktimarc/kst4contest/issues/113) behoben.
 
 ### Hinweise zur Aktualisierung
 

github_docs/de-Installation.md

@@ -221,6 +221,8 @@ sudo apt install ./KST4Contest-v<Version>-debian-amd64.deb
 
 Alternativ kann die Datei in einer grafischen Paketverwaltung geöffnet werden.
 
+Beta-Pakete tragen hinter der Version eine Vorab-Release-Nummer (`1.50.0-0.beta.001`), die unter der des stabilen Pakets (`1.50.0-1`) liegt; das stabile Paket installiert sich daher als Aktualisierung über eine Beta.
+
 ### Fedora und kompatible RPM-Systeme
 
 Installiere das RPM-Paket mit:
@@ -229,6 +231,8 @@ Installiere das RPM-Paket mit:
 sudo dnf install ./KST4Contest-v<Version>-fedora-x86_64.rpm
 ```
 
+Beta-Pakete tragen hinter der Version eine Vorab-Release-Nummer (`1.50.0-0.beta.001`), die unter der des stabilen Pakets (`1.50.0-1`) liegt; das stabile Paket installiert sich daher als Aktualisierung über eine Beta.
+
 ### Arch Linux: fertiges Release-Paket
 
 Das aus dem GitHub Release heruntergeladene Arch-Paket kann direkt installiert werden:

github_docs/en-Changelog.md

@@ -46,6 +46,7 @@ Several operators sharing one computer can now use their own callsigns, locators
 - **No automatic cluster spots for worked stations:** the local DX Cluster server generated spots from directional opportunities without checking the worked state. A spot is no longer created when the station has already been worked on the band of the detected frequency; without per-band information the global worked state counts. Manual spots from the map and the test spot in the settings are unchanged. This fixes [Issue #91](https://github.com/praktimarc/kst4contest/issues/91).
 - **QSO monitoring no longer picks up foreign entries:** besides the list of monitored callsigns, `preferences.xml` carried a second list `snifferWords` that never appeared in the user interface. On loading, its entries were nevertheless added to QSO monitoring as callsigns. The dead list is removed; a `snifferWords` element in older files is ignored. This fixes [Issue #103](https://github.com/praktimarc/kst4contest/issues/103).
 - **No second-category locator any more:** internally there was a setting for a separate locator of the second chat category that appeared neither in the user interface nor in `preferences.xml`, so it always kept its compiled-in default. During login that default was compared with the station's locator and a warning was emitted that the second locator is ignored. ON4KST uses one locator per TCP session anyway; the setting and the warning are removed. This fixes [Issue #104](https://github.com/praktimarc/kst4contest/issues/104).
+- **Linux beta packages upgrade to the stable package:** DEB and RPM packages of a beta tag carried the same version number as the following stable package, so `dnf` and `dpkg` refused the upgrade as an equal version. Beta packages now carry a pre-release number (`1.50.0-0.beta.001`) below the stable package (`1.50.0-1`), and the release run aborts when the tag does not match `composePackageVersion`. This fixes [Issue #113](https://github.com/praktimarc/kst4contest/issues/113).
 
 ### Upgrade notes
 

github_docs/en-Installation.md

@@ -221,6 +221,8 @@ sudo apt install ./KST4Contest-v<version>-debian-amd64.deb
 
 Alternatively, open the file with a graphical package manager.
 
+Beta packages carry a pre-release number behind the version (`1.50.0-0.beta.001`) that sorts below the stable package (`1.50.0-1`), so the stable package installs as an upgrade over a beta.
+
 ### Fedora and compatible RPM systems
 
 Install the RPM package with:
@@ -229,6 +231,8 @@ Install the RPM package with:
 sudo dnf install ./KST4Contest-v<version>-fedora-x86_64.rpm
 ```
 
+Beta packages carry a pre-release number behind the version (`1.50.0-0.beta.001`) that sorts below the stable package (`1.50.0-1`), so the stable package installs as an upgrade over a beta.
+
 ### Arch Linux: installing the release package
 
 The Arch package downloaded from the GitHub Release can be installed directly: