Merge branch 'clarify-settings-migration-procedure'

5 files changed, 85 insertions, 1 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 82b26a4772..d3f9a756a9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -197,6 +197,7 @@ This release is identical to 2021.5-beta2 except that it has translations for ne
 - Update Electron from 11.2.3 to 11.4.9.
 - Move OpenVPN and WireGuard settings in the advanced settings view into separate settings views.
 - Return to main view in desktop app after being hidden/closed for two minutes.
+- Settings format updated from `v3` to `v5`.
 
 #### Linux
 - Always send DNS requests inside the tunnel for excluded processes when using public custom DNS.
@@ -365,6 +366,7 @@ This release is for desktop only.
 - Show default, minimum, and maximum key rotation intervals in CLI.
 - Attempt to send problem reports using other endpoints if using the primary one fails.
 - Upgrade wireguard-go to version 20210225140808 (Windows: v0.3.8)
+- Settings format updated to `v3`.
 
 ### Fixed
 - Fix GUI not showing correct view if disconnected from the daemon during app startup.
@@ -1433,6 +1435,7 @@ This release is identical to 2019.8-beta1
 - Upgrade OpenVPN from 2.4.6 to 2.4.7.
 - Upgrade OpenSSL from 1.1.0h to 1.1.1c.
 - Upgrade wireguard-go library to v0.0.20190805.
+- Settings format updated to `v2`.
 
 ### Fixed
 - Mark CLI `bridge set state` argument as required to avoid a crash.
diff --git a/mullvad-daemon/src/migrations/mod.rs b/mullvad-daemon/src/migrations/mod.rs
index 3ba962aaea..bb2d7fe3ea 100644
--- a/mullvad-daemon/src/migrations/mod.rs
+++ b/mullvad-daemon/src/migrations/mod.rs
@@ -18,6 +18,18 @@
 //!
 //! Any other type must be vendored into the migration module so the format
 //! it has is locked over time.
+//!
+//! There should never be multiple migrations between two official releases. At most one.
+//! Between releases, dev builds can break the settings without having a proper migration path.
+//!
+//! # Creating a migration
+//!
+//! 1. Copy `vX.rs.template` to `vX.rs` where `X` is the latest settings version right now.
+//! 1. Add the new version (`Y = X+1`) to `SettingsVersion` and bump `CURRENT_SETTINGS_VERSION`
+//!    to `Y`.
+//! 1. Write a comment in the new module about how the format changed, what it needs to migrate.
+//! 1. Implement the migration and add adequate tests.
+//! 1. Add to the changelog: "Settings format updated to `vY`"
 
 use std::path::Path;
 use tokio::{
@@ -30,6 +42,7 @@ mod v1;
 mod v2;
 mod v3;
 mod v4;
+// Not yet done. Add to this instead of creating v6 for now.
 mod v5;
 
 const SETTINGS_FILE: &str = "settings.json";
diff --git a/mullvad-daemon/src/migrations/v5.rs b/mullvad-daemon/src/migrations/v5.rs
index ad788ab834..0fcaca4e08 100644
--- a/mullvad-daemon/src/migrations/v5.rs
+++ b/mullvad-daemon/src/migrations/v5.rs
@@ -7,6 +7,25 @@ use mullvad_types::settings::SettingsVersion;
 
 // ======================================================
 
+/// This is an open ended migration. There is no v6 yet!
+/// The migrations performed by this function are still backwards compatible.
+/// The JSON coming out of this migration can be read by any v5 compatible daemon.
+///
+/// When further migrations are needed, add them here and if they are not backwards
+/// compatible then create v6 and "close" this migration for further modification.
+///
+/// # Changes to the format
+///
+/// The ability to disable WireGuard multihop while preserving the entry location was added.
+/// So a new field, `use_multihop` is introduced. We want this to default to `true` iff:
+///  * `use_mulithop` was not present in the settings
+///  * A multihop entry location had been previously specified.
+///
+/// This change is backwards compatible since older daemons will just ignore `use_multihop` if
+/// present.
+///
+/// It is also no longer valid to have `entry_location` set to null. So remove the field if it
+/// is null in order to make it default back to the default location.
 pub fn migrate(settings: &mut serde_json::Value) -> Result<()> {
     if !version_matches(settings) {
         return Ok(());
@@ -35,7 +54,9 @@ pub fn migrate(settings: &mut serde_json::Value) -> Result<()> {
         }
     }
 
-    // Note: Not incrementing the version number
+    // Note: Not incrementing the version number yet, since this migration is still open
+    // for future modification.
+    // settings["settings_version"] = serde_json::json!(SettingsVersion::V6);
 
     Ok(())
 }
diff --git a/mullvad-daemon/src/migrations/vX.rs.template b/mullvad-daemon/src/migrations/vX.rs.template
new file mode 100644
index 0000000000..349145db13
--- /dev/null
+++ b/mullvad-daemon/src/migrations/vX.rs.template
@@ -0,0 +1,43 @@
+use super::Result;
+use mullvad_types::{relay_constraints::Constraint, settings::SettingsVersion};
+
+// ======================================================
+// Section for vendoring types and values that
+// this settings version depend on. See `mod.rs`.
+
+// ...
+
+// ======================================================
+
+/// TODO: Write in this documentation how the settings format changed, what the migration does.
+pub fn migrate(settings: &mut serde_json::Value) -> Result<()> {
+    if !version_matches(settings) {
+        return Ok(());
+    }
+
+    // TODO
+    log::info!("Migrating settings format to V${CURRENT_VERSION+1}");
+
+    // TODO: Insert migration code here
+
+    // TODO
+    settings["settings_version"] = serde_json::json!(SettingsVersion::V${CURRENT_VERSION + 1});
+
+    Ok(())
+}
+
+fn version_matches(settings: &mut serde_json::Value) -> bool {
+  settings
+      .get("settings_version")
+      // TODO
+      .map(|version| version == SettingsVersion::V${CURRENT_VERSION} as u64)
+      .unwrap_or(false)
+}
+
+#[cfg(test)]
+mod test {
+    use super::{migrate, version_matches};
+    use serde_json;
+
+    // TODO: Implement tests. Look at other migration modules for inspiration.
+}
diff --git a/mullvad-types/src/settings/mod.rs b/mullvad-types/src/settings/mod.rs
index f31a53212f..26a24202a5 100644
--- a/mullvad-types/src/settings/mod.rs
+++ b/mullvad-types/src/settings/mod.rs
@@ -13,6 +13,10 @@ use std::net::IpAddr;
 use std::{collections::HashSet, path::PathBuf};
 use talpid_types::net::{self, openvpn, GenericTunnelOptions};
 
+/// The version used by the current version of the code. Should always be the
+/// latest version that exists in `SettingsVersion`.
+/// This should be bumped when a new version is introduced along with a migration
+/// being added to `mullvad-daemon`.
 pub const CURRENT_SETTINGS_VERSION: SettingsVersion = SettingsVersion::V5;
 
 #[derive(Debug, PartialEq, PartialOrd, Clone, Copy)]