Add instructions in migrations/mod.rs about how to create a migration

4 files changed, 67 insertions, 1 deletions

diff --git a/mullvad-daemon/src/migrations/mod.rs b/mullvad-daemon/src/migrations/mod.rs
index 3ba962aaea..d14b95b0cc 100644
--- a/mullvad-daemon/src/migrations/mod.rs
+++ b/mullvad-daemon/src/migrations/mod.rs
@@ -18,6 +18,17 @@
 //!
 //! 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 `v$CURRENT_VERSION.rs` where `$CURRENT_VERSION` is the version
+//!    specified under `settings_version` when running the last stable official release of the app.
+//! 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: "New settings version: ${CURRENT_VERSION + 1}."
 
 use std::path::Path;
 use tokio::{
diff --git a/mullvad-daemon/src/migrations/v5.rs b/mullvad-daemon/src/migrations/v5.rs
index ad788ab834..c03717684b 100644
--- a/mullvad-daemon/src/migrations/v5.rs
+++ b/mullvad-daemon/src/migrations/v5.rs
@@ -7,6 +7,12 @@ 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.
 pub fn migrate(settings: &mut serde_json::Value) -> Result<()> {
     if !version_matches(settings) {
         return Ok(());
@@ -35,7 +41,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)]