docs: add new "sort-key" field to boot loader spec

This allows snippet generators to explicitly order entries: any string
can be set as an entry's "sort key". If set, sd-boot will use it to sort
entries on display.

New logic is hence (ignore the boot counting logic)

  sort-key is set → primary sort key: sort-key (lexicographically increasing order)
                  → secondary sort key: machine-id (also increasing order)
                  → tertiary sort key: version (lexicographically decreasing order!)

  sort-key is not set → primary sort key: entry filename (aka id), lexicographically increasing order)

With this scheme we can order OSes by their names from A-Z but then put
within the same OS still the newest version first. This should clean up
the order to match expectations more.

Based on discussions here:

https://github.com/systemd/systemd/pull/22391#issuecomment-1040092633

1 files changed, 16 insertions, 5 deletions

diff --git a/docs/BOOT_LOADER_SPECIFICATION.md b/docs/BOOT_LOADER_SPECIFICATION.md
index 8653a5bc00..7f15a23164 100644
--- a/docs/BOOT_LOADER_SPECIFICATION.md
+++ b/docs/BOOT_LOADER_SPECIFICATION.md
@@ -232,6 +232,16 @@ spaces from its value. The following keys are known:
   other installed operating systems. This ID shall be formatted as 32 lower
   case hexadecimal characters (i.e. without any UUID formatting). This key is
   optional. Example: `4098b3f648d74c13b1f04ccfba7798e8`.
+* `sort-key` shall contain a short string used for sorting entries on
+  display. This can be defined freely though should typically be initialized
+  from `IMAGE_ID=` or `ID=` from `/etc/os-release` of the relevant entry,
+  possibly suffixed. This field is optional. If set, it is used as primary
+  sorting key for the entries on display (lexicographically increasing). It
+  does not have to be unique (and usually is not). If non-unique the the
+  `machine-id` (lexicographically increasing) and `version` (lexicographically
+  decreasing, i.e. newest version first) fields described above are used as
+  secondary/ternary sorting keys. If this field is not set entries are
+  typically sorted by the `.conf` file name of the entry.
 * `linux` refers to the Linux kernel to spawn and shall be a path relative to
   `$BOOT`. It is recommended that every distribution creates a machine id and
   version specific subdirectory below `$BOOT` and places its kernels and
@@ -269,8 +279,9 @@ key and is otherwise not valid. Here's an example for a complete drop-in file:
 
     # /boot/loader/entries/6a9857a393724b7a981ebb5b8495b9ea-3.8.0-2.fc19.x86_64.conf
     title        Fedora 19 (Rawhide)
-    version      3.8.0-2.fc19.x86_64
+    sort-key     fedora
     machine-id   6a9857a393724b7a981ebb5b8495b9ea
+    version      3.8.0-2.fc19.x86_64
     options      root=UUID=6d3376e4-fc93-4509-95ec-a21d68011da2
     architecture x64
     linux        /6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/linux
@@ -358,10 +369,10 @@ simply reads all files `$BOOT/loader/entries/*.conf`, and populates its boot
 menu with this. On EFI, it then extends this with any unified kernel images
 found in `$BOOT/EFI/Linux/*.efi`. It may also add additional entries, for
 example a "Reboot into firmware" option. Optionally it may sort the menu based
-on the `machine-id` and `version` fields, and possibly others. It uses the file
-name to identify specific items, for example in case it supports storing away
-default entry information somewhere. A boot loader should generally not modify
-these files.
+on the `sort-key`, `machine-id` and `version` fields, and possibly others. It
+uses the file name to identify specific items, for example in case it supports
+storing away default entry information somewhere. A boot loader should
+generally not modify these files.
 
 For "Boot Loader Specification Entries" (Type #1), the _kernel package
 installer_ installs the kernel and initrd images to `$BOOT` (it is recommended