From 3588f06767c664ec740b4c6c71e1245e8d1158e1 Mon Sep 17 00:00:00 2001
From: Adriaan de Groot <groot@kde.org>
Date: Fri, 19 Mar 2021 12:49:37 +0100
Subject: [PATCH] [netinstall] Document groupsUrl with multiple entries

---
 src/modules/netinstall/netinstall.conf | 48 +++++++++++++++++---------
 1 file changed, 32 insertions(+), 16 deletions(-)

diff --git a/src/modules/netinstall/netinstall.conf b/src/modules/netinstall/netinstall.conf
index c377b526e..d38c0b040 100644
--- a/src/modules/netinstall/netinstall.conf
+++ b/src/modules/netinstall/netinstall.conf
@@ -32,20 +32,21 @@
 # This module supports multiple instances through the *label* key,
 # which allows you to distinguish them in the UI.
 ---
-# This is the URL that is retrieved to get the netinstall groups-and-packages
-# data (which should be in the format described in netinstall.yaml), e.g.:
-#    ```
-#    groupsUrl: http://example.org/netinstall.php
-#    ```
-# or it can be a locally installed file:
-#    ```
-#    groupsUrl: file:///usr/share/calamares/netinstall.yaml
-#    ```
-# or it can be the special-case literal string "local":
-#    ```
-#    groupsUrl: local
-#    ```
+# The *groupsUrl* determines where the data for the netinstall groups-and-
+# packages comes from. The value of the key may be:
 #
+# - a single string (this is treated as a list with just that string in it)
+# - a list of strings
+#
+# Each string is treated as a URL (see below for special cases. The
+# list is examined **in order** and each URL is tried in turn. The
+# first URL to load successfully -- even if it yields 0 packages --
+# ends the process. This allows using a network URL and a (fallback)
+# local URL for package lists, or for using multiple mirrors of
+# netinstall data.
+#
+# The URL must point to a YAML file that follows the format described
+# below at the key *groups* -- except for the special case URL "local".
 # Note that the contents of the groups file is the **important**
 # part of the configuration of this module. It specifies what
 # groups and packages the user may select (and so what commands are to
@@ -59,12 +60,27 @@
 # must have a list-of-groups as value; if the file does not have
 # a top-level key *groups*, then the file must contain only a list of groups.
 #
-# As a special case, setting *groupsUrl* to the literal string
-# `local` means that the data is obtained from **this** config
-# file, under the key *groups*.
+# Each item in the list *groupsUrl* may be:
+# - A remote URL like `http://example.org/netinstall.php`
+# - A local file URL like `file:///usr/share/calamares/netinstall.yaml`
+# - The special-case literal string `local`
+#
+# Non-special case URLs are loaded as YAML; if the load succeeds, then
+# they are interpreted like the *groups* key below. The special case
+# `local` loads the data directly from **this** file.
 #
 groupsUrl: local
 
+# Alternate form:
+# groupsUrl: [ local ]
+
+# Net-based package list, with fallback to local file
+# groupsUrl:
+#   - http://example.com/calamares/netinstall.yaml
+#   - file:///etc/calamares/modules/netinstall.yaml
+
+
+
 # If the installation can proceed without netinstall (e.g. the Live CD
 # can create a working installed system, but netinstall is preferred
 # to bring it up-to-date or extend functionality) leave this set to