From 9ca6d3c71532b34af6d12ace074b1a58847ff90b Mon Sep 17 00:00:00 2001
From: Adriaan de Groot <groot@kde.org>
Date: Mon, 11 Apr 2022 14:26:29 +0200
Subject: [PATCH] [users] Document new template setting for hostname

---
 CHANGES-3.2                         |  5 +++++
 src/modules/users/users.conf        | 22 ++++++++++++++++++++--
 src/modules/users/users.schema.yaml |  1 +
 3 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/CHANGES-3.2 b/CHANGES-3.2
index 578590134..a1387d99c 100644
--- a/CHANGES-3.2
+++ b/CHANGES-3.2
@@ -23,6 +23,11 @@ This release contains contributions from (alphabetically by first name):
  - *users* module has a new hostname.location setting, *Transient*, which
    will force the installed system to transient-hostname-setting by removing
    the file `/etc/hostname`.
+ - *users* module has a new hostname.template setting, which allows some
+   tweaking of how the hostname suggestion is constructed. In particular,
+   it can be configured to use the current hostname (whatever that may be).
+   See the example `users.conf` for details on available keys.
+
 
 # 3.2.54 (2022-03-21) #
 
diff --git a/src/modules/users/users.conf b/src/modules/users/users.conf
index c5cc8d2af..60284b74e 100644
--- a/src/modules/users/users.conf
+++ b/src/modules/users/users.conf
@@ -156,7 +156,7 @@ userShell: /bin/bash
 # a default / suggestion) and where (or how) the hostname is set in
 # the target system.
 #
-# Key *hostname* has the following sub-keys (just one):
+# Key *hostname* has the following sub-keys:
 #
 # - *location* How the hostname is set in the target system:
 #   - *None*, to not set the hostname at all
@@ -164,14 +164,32 @@ userShell: /bin/bash
 #   - *Etc*, identical to above
 #   - *Hostnamed*, to use systemd hostnamed(1) over DBus
 #   - *Transient*, to remove `/etc/hostname` from the target
-#   The default is *EtcFile*. Setting this to *None* will
+#   The default is *EtcFile*. Setting this to *None* or *Transient* will
 #   hide the hostname field.
 # - *writeHostsFile* Should /etc/hosts be written with a hostname for
 #   this machine (also adds localhost and some ipv6 standard entries).
 #   Defaults to *true*.
+# - *template* Is a simple template for making a suggestion for the
+#   hostname, based on user data. The default is "${first}-${product}".
+#   This is used only if the hostname field is shown. KMacroExpander is
+#   used; write `${key}` where `key` is one of the following:
+#   - *first* User's first name (whatever is first in the User Name field,
+#     which is first-in-order but not necessarily a "first name" as in
+#     "given name" or "name by which you call someone"; beware of western bias)
+#   - *name* All the text in the User Name field.
+#   - *login* The login name (which may be suggested based on User Name)
+#   - *product* The hardware product, based on DMI data
+#   - *product2* The product as described by Qt
+#   - *cpu* CPU name
+#   - *host* Current hostname (which may be a transient hostname)
+#   Literal text in the template is preserved. Calamares tries to map
+#   `${key}` values to something that will fit in a hostname, but does not
+#   apply the same to literal text in the template. Do not use invalid
+#   characters in the literal text, or no suggeston will be done.
 hostname:
   location: EtcFile
   writeHostsFile: true
+  template: "derp-${cpu}"
 
 # TODO:3.3: Remove this setting
 #
diff --git a/src/modules/users/users.schema.yaml b/src/modules/users/users.schema.yaml
index c7088253a..fe45d5fb2 100644
--- a/src/modules/users/users.schema.yaml
+++ b/src/modules/users/users.schema.yaml
@@ -46,6 +46,7 @@ properties:
         properties:
             location: { type: string, enum: [ None, EtcFile, Hostnamed, Transient ] }
             writeHostsFile: { type: boolean, default: true }
+            template: { type: string, default: "${first}-${product}" }
     # Legacy Hostname setting
     setHostname: { type: string, enum: [ None, EtcFile, Hostnamed ] }
     writeHostsFile: { type: boolean, default: true }