From 16ca5afa2ef362a650cea24b7c78b4568127f7a1 Mon Sep 17 00:00:00 2001
From: Sebastian Wiesner <sebastian@swsnr.de>
Date: Thu, 2 Jan 2025 18:37:06 +0100
Subject: [PATCH] Define versioning policy

Specifically, reserve patch releases for releases without release notes
such as translation updates, to be able to ship meaningful release notes
to users while updating translations at any point in time.

Adapt the about dialog to show the cargo version number, but use only
its major and minor parts for the release notes version number.
---
 Cargo.lock           |  1 +
 Cargo.toml           | 12 ++++++++++++
 src/app.rs           |  4 ++--
 src/app/debuginfo.rs |  2 +-
 src/config.rs        | 28 +++++++++++++++++++++++++---
 src/main.rs          |  2 +-
 6 files changed, 42 insertions(+), 7 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 50583f8..c2ff2a8 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -760,6 +760,7 @@ dependencies = [
  "libadwaita",
  "log",
  "macaddr",
+ "semver",
  "serde",
  "serde_json",
  "socket2",
diff --git a/Cargo.toml b/Cargo.toml
index c023fec..b193bcb 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -5,6 +5,17 @@ homepage = "https://github.com/swsnr/turnon"
 repository = "https://github.com/swsnr/turnon"
 license = "MPL-2.0"
 authors = ["Sebastian Wiesner <sebastian@swsnr.de>"]
+# Our version number.  Since semver doesn't make much sense for UI applications
+# which have no API we repurpose the version numer as follows:
+#
+# - major: Major new features or major changes to the UI, which may break the app for some users.
+# - minor: User-visible features or bugfixes.
+# - patch: Translation updates.
+#
+# Major and minor releases get release notes, but patch releases do not; this
+# enables us to ship updates to translations whenever translators contributed
+# new languages or made major updates, while still providing meaningful release
+# notes for the last functional changes.
 version = "2.1.0"
 edition = "2021"
 publish = false
@@ -22,6 +33,7 @@ serde = { version = "1.0.210", features = ["derive"] }
 serde_json = "1.0.128"
 socket2 = "0.5.7"
 bitflags = "2.6.0"
+semver = "1.0.24"
 
 [build-dependencies]
 glob = "0.3.1"
diff --git a/src/app.rs b/src/app.rs
index ed0905b..5eb058e 100644
--- a/src/app.rs
+++ b/src/app.rs
@@ -31,9 +31,9 @@ impl TurnOnApplication {
     fn show_about_dialog(&self) {
         let dialog = adw::AboutDialog::from_appdata(
             "/de/swsnr/turnon/de.swsnr.turnon.metainfo.xml",
-            Some(crate::config::VERSION),
+            Some(&crate::config::release_notes_version()),
         );
-        dialog.set_version(crate::config::VERSION);
+        dialog.set_version(crate::config::CARGO_PKG_VERSION);
 
         glib::spawn_future_local(glib::clone!(
             #[strong(rename_to = devices)]
diff --git a/src/app/debuginfo.rs b/src/app/debuginfo.rs
index 368da72..0376efb 100644
--- a/src/app/debuginfo.rs
+++ b/src/app/debuginfo.rs
@@ -119,7 +119,7 @@ impl DebugInfo {
         .unwrap();
         DebugInfo {
             app_id: config::APP_ID,
-            version: config::VERSION,
+            version: config::CARGO_PKG_VERSION,
             flatpak: config::running_in_flatpak(),
             connectivity,
             ping_results,
diff --git a/src/config.rs b/src/config.rs
index ab9f5f4..3019f2a 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -4,7 +4,7 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
-use std::path::PathBuf;
+use std::{borrow::Cow, path::PathBuf};
 
 use glib::{gstr, GStr};
 use gtk::gio;
@@ -12,8 +12,30 @@ use gtk::gio;
 /// The app ID to use.
 pub static APP_ID: &GStr = gstr!("de.swsnr.turnon");
 
-/// The app version.
-pub static VERSION: &str = env!("CARGO_PKG_VERSION");
+/// The Cargo package verson.
+///
+/// This provides the full version from `Cargo.toml`.
+pub static CARGO_PKG_VERSION: &str = env!("CARGO_PKG_VERSION");
+
+/// The version to use for release notes.
+///
+/// For nightly builds (see [`is_development`]) this returns `next`, otherwise
+/// it returns [`CARGO_PKG_VERSION`] but with patch set to 0, and all pre and
+/// build parts emptied.
+///
+/// This follows our versioning policy which uses patch releases only for
+/// translation updates.
+pub fn release_notes_version() -> Cow<'static, str> {
+    if is_development() {
+        Cow::Borrowed("next")
+    } else {
+        let mut version = semver::Version::parse(CARGO_PKG_VERSION).unwrap();
+        version.patch = 0;
+        version.pre = semver::Prerelease::EMPTY;
+        version.build = semver::BuildMetadata::EMPTY;
+        version.to_string().into()
+    }
+}
 
 pub const G_LOG_DOMAIN: &str = "TurnOn";
 
diff --git a/src/main.rs b/src/main.rs
index fd07b48..ddabe2d 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -48,6 +48,6 @@ fn main() -> glib::ExitCode {
     glib::set_application_name("Turn On");
 
     let app = TurnOnApplication::default();
-    app.set_version(config::VERSION);
+    app.set_version(config::CARGO_PKG_VERSION);
     app.run()
 }