Add docs for upgrade from legacy table to gpt

[KFearsoff]

I've been getting the following warning for some time now:

trace: warning: The legacy table is outdated and should not be used. We recommend using the gpt type instead.
Please note that certain features, such as the test framework, may not function properly with the legacy table type.
If you encounter errors similar to:
"error: The option `disko.devices.disk.disk1.content.partitions."[definition 1-entry 1]".content._config` is read-only, but it's set multiple times,"
this is likely due to the use of the legacy table type.

I have two configurations that share this problem:
https://github.com/KFearsoff/NixOS-config/blob/02fbc8af10edf6757de61fd413f5451fefce9d21/hosts/blueberry/disko.nix
https://github.com/KFearsoff/NixOS-config/blob/02fbc8af10edf6757de61fd413f5451fefce9d21/hosts/cloudberry/disko.nix

From the existing documentation, it is not clear to me how the upgrade path should look. In particular, I have the following points of confusion:

• Does flags = ["bios_grub"]; directly map to type = "EF02";?
• For blueberry host (first link), I have ESP partition starting at 1MiB and ending at 512MiB. Examples seems to specify size instead, which, if I understand it correctly, would brick my boot. Are start and end options still supported?
• Is bootable = true; flag still necessary for ESP partition?
• Do I need to specify priority = 1; for ESP partition?
• For cloudberry host (second link), do I need to specify fs-type = "fat32"; for my boot partition?
• How did the API change in GPT format compared to legacy table format? What endpoints had breaking changes? What endpoints aren't supported anymore? What are deprecated? What have better implementations ready?

Perhaps the above questions are trivial to answer, but I haven't found any docs for them. And I would like to err on the side of caution when it comes to changing the filesystem layout.

[Lassulus]

* Does `flags = ["bios_grub"];` directly map to `type = "EF02";`?

yes

* For blueberry host (first link), I have ESP partition starting at 1MiB and ending at 512MiB. Examples seems to specify `size` instead, which, if I understand it correctly, would brick my boot. Are `start` and `end` options still supported?

you can also specify start and end instead, but even changing your disk layout won't run disko again and your disks will remain the way they are now. What is important though, is to create a partlabels disko would have created if you would run it with the gpt type.

* Is `bootable = true;` flag still necessary for ESP partition?

no, it never had any effect on gpt partitions.

* Do I need to specify `priority = 1;` for ESP partition?

some people say it's necessary, but I never had a device where this was an issue. it shouldn't matter for the ESP partition but the EF02 partition could be important.

* For cloudberry host (second link), do I need to specify `fs-type = "fat32";` for my boot partition?

fs-type never had any effect on gpt partitions.

* How did the API change in GPT format compared to legacy table format? What endpoints had breaking changes? What endpoints aren't supported anymore? What are deprecated? What have better implementations ready?

the newer gpt format uses attrsets instead of lists. the legacy table used parted the new gpt uses sgdisk, which has a better interface for scripting.

Perhaps the above questions are trivial to answer, but I haven't found any docs for them. And I would like to err on the side of caution when it comes to changing the filesystem layout.

[nifoc]

I would also very much appreciate a guide on how to move from table to gpt.

Or a definitive statement that it's not possible and we either have to a) live with the warnings or b) re-install.

Ref: #538 (comment)

[KFearsoff]

So, I've tried updating (and failed miserably). Some of the gotchas I've noticed are:

• "name" for "table" is partlabel. For "gpt" you need to set "label" instead; "name" is something else
• Somehow cloudberry ended up with mirroredBoots after trying to migrate. My best guess is that my config entry boot.loader.grub.device = "nodev" conflicts with how Disko tries to add partitions that have "EF02" to boot.loader.grub.devices (note the trailing s)

[nifoc]

Is there any way to specifically sponsor/fund documentation for moving from legacy table to GPT?

[Lassulus]

we now have a guide for migration: https://github.com/nix-community/disko/blob/master/docs/table-to-gpt.md