From 8ac50aa153b80f6cc525ac35cd1a712d0d76d3c6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= <joerg@thalheim.io>
Date: Sat, 15 Apr 2023 16:04:05 +0200
Subject: [PATCH] improve changelog

---
 BREAKING_CHANGES.md   |  23 ---------
 README.md             |   4 ++
 docs/upgrade-guide.md | 105 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 109 insertions(+), 23 deletions(-)
 delete mode 100644 BREAKING_CHANGES.md
 create mode 100644 docs/upgrade-guide.md

diff --git a/BREAKING_CHANGES.md b/BREAKING_CHANGES.md
deleted file mode 100644
index 0d07452..0000000
--- a/BREAKING_CHANGES.md
+++ /dev/null
@@ -1,23 +0,0 @@
-2023-04-07 7d70009
-
-zfs_datasets are now split into zfs_fs and zfs_volume. zfs_type got removed. size is only available for zfs_volume
-
-2023-04-07 654ecb3
-
-lvm_lv types are always part of a lvm_vg and it is no longer possible (and neccessary) to specify the type
-
-2023-04-07 d6f062e
-
-parition types are always part of a table and it is no longer possible (and neccessary) to specify the type
-
-2023-03-22 2624af6
-
-disk config now needs to be inside a disko.devices attrset always
-
-2023-03-22 0577409
-
-the extraArgs option in the luks type was renamed to extraFormatArgs
-
-2023-02-14 6d630b8
-
-btrfs, btrfs_subvol filesystem and lvm_lv extraArgs are now lists
diff --git a/README.md b/README.md
index f211f92..d0e75d5 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,10 @@ For a NixOS installation follow this [quickstart guide](./docs/quickstart.md).
 
 ### Using without NixOS
 
+### Upgrading from older disko versions
+
+Read our [upgrade guide](/docs/upgrade-guide.md) when updating from older versions.
+
 ## Reference
 
 ### Module options
diff --git a/docs/upgrade-guide.md b/docs/upgrade-guide.md
new file mode 100644
index 0000000..7a6ceef
--- /dev/null
+++ b/docs/upgrade-guide.md
@@ -0,0 +1,105 @@
+2023-04-07 7d70009
+
+Changes:
+
+- ZFS datasets have been split into two types: `zfs_fs` and `zfs_volume`.
+- The `zfs_type` attribute has been removed.
+- The size attribute is now only available for `zfs_volume`.
+
+Updated example/zfs.nix file:
+
+```nix
+datasets = {
+  zfs_fs = {
+    type = "zfs_fs";
+    mountpoint = "/zfs_fs";
+    options."com.sun:auto-snapshot" = "true";
+  };
+  zfs_unmounted_fs = {
+    type = "zfs_fs";
+    options.mountpoint = "none";
+  };
+  zfs_legacy_fs = {
+    type = "zfs_fs";
+    options.mountpoint = "legacy";
+    mountpoint = "/zfs_legacy_fs";
+  };
+  zfs_testvolume = {
+    type = "zfs_volume";
+    size = "10M";
+    content = {
+      type = "filesystem";
+      ...
+
+Note: The `zfs_type` attribute has been replaced with a type attribute for each dataset, and the `size` attribute is only available for `zfs_volume`.
+These changes have been reflected in the example/zfs.nix file.
+```
+
+2023-04-07 654ecb3
+
+The `lvm_lv` type is always part of an `lvm_vg` and it is no longer necessary to specify the type.
+
+This means that if you were using the `lvm_lv` type in your code, you should remove it and make sure to only use the `lvm_vg` type. 
+For example, if you were defining an `lvm_lv` type like this:
+
+```nix
+{
+  type = "lvm_lv";
+  size = "10G";
+  # ...
+}
+
+You should now define it like this:
+
+
+```nix
+{
+  size = "10G";
+  # ...
+}
+```
+
+Note that the `type` field is no longer necessary and should be removed from your code.
+
+2023-04-07 d6f062e
+
+Partition types are now always part of a table and cannot be specified individually anymore. This change makes the library more consistent and easier to use.
+
+Example of how to change code:
+
+Before:
+
+```nix
+{
+  type = "partition";
+  name = "ESP";
+  start = "1MiB";
+  end = "100MiB";
+  part-type = "primary";
+}
+```
+
+After:
+
+```nix
+{
+  name = "ESP";
+  start = "1MiB";
+  end = "100MiB";
+  part-type = "primary";
+}
+```
+
+Note that the `type` field is no longer necessary and should be removed from your code.
+
+2023-03-22 2624af6
+
+disk config now needs to be inside a disko.devices attrset always
+
+2023-03-22 0577409
+
+the extraArgs option in the luks type was renamed to extraFormatArgs
+
+2023-02-14 6d630b8
+
+btrfs, btrfs_subvol filesystem and lvm_lv extraArgs are now lists