From 1d19afc2a790c21e62d37abe1cbdc15c34c9489b Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Jun 09 2023 01:52:14 +0000 Subject: [PATCH 1/2] Per-Product Configuration: semantic newlines --- diff --git a/guidelines/modules/ROOT/pages/Per-Product_Configuration.adoc b/guidelines/modules/ROOT/pages/Per-Product_Configuration.adoc index 6b94199..62de955 100644 --- a/guidelines/modules/ROOT/pages/Per-Product_Configuration.adoc +++ b/guidelines/modules/ROOT/pages/Per-Product_Configuration.adoc @@ -1,32 +1,72 @@ -In the Fedora.next world, we have a set of curated Fedora Products as well as the availability of classic Fedora. Historically, we have maintained a single set of configuration defaults for all Fedora installs, but different target use-cases have different needs. The goal of this document is to set out the guidelines for creating per-Product configuration defaults. - -We want to ensure that all packages have sensible defaults for whichever Product on which they are installed, while also avoiding situations where users would have some packages installed with one Product's defaults and some packages with another. +In the Fedora.next world, +we have a set of curated Fedora Products as well as the availability of classic Fedora. +Historically, we have maintained a single set of configuration defaults +for all Fedora installs, +but different target use-cases have different needs. +The goal of this document +is to set out the guidelines for creating per-Product configuration defaults. + +We want to ensure that all packages have sensible defaults +for whichever Product on which they are installed, +while also avoiding situations where users would have some packages installed +with one Product's defaults and some packages with another. == Per-product Configuration Packaging === Requirements -* All packages MUST have a global default configuration. This configuration will be used whenever a Product-specific default configuration is not required. (For example, if a non-Product install is in use or only Fedora Cloud has a custom configuration and Fedora Workstation was installed). -* Any package that requires a per-product default configuration MUST provide all alternate configuration files in the same package. -* Any package that requires a configuration that differs between Products MUST obtain permission from that Product's Working Group before packaging it. +* All packages MUST have a global default configuration. + This configuration will be used + whenever a Product-specific default configuration is not required. + (For example, if a non-Product install is in use + or only Fedora Cloud has a custom configuration + and Fedora Workstation was installed). +* Any package that requires a per-product default configuration + MUST provide all alternate configuration files in the same package. +* Any package that requires a configuration that differs between Products + MUST obtain permission from that Product's Working Group before packaging it. === Global Default Configuration -* The global default configuration MUST be provided by the package that requires it. -* The global default configuration MUST be named based on the package's normal naming scheme, with the main part of the name being suffixed by -default. For example, if the package normally uses foo.conf, then the global default configuration MUST be named foo-default.conf +* The global default configuration + MUST be provided by the package that requires it. +* The global default configuration + MUST be named based on the package's normal naming scheme, + with the main part of the name being suffixed by -default. + For example, if the package normally uses foo.conf, + then the global default configuration MUST be named foo-default.conf === Per-Product Default Configuration -* For each Product requiring a unique default configuration, the packager MUST provide a copy of the default configuration file, modified as appropriate for the specific product. -* The product-specific configuration file MUST be named based on the package's normal naming scheme, with the main part of the name being suffixed by a dash followed by the name of the product. For example, if the package normally uses `+foo.conf+`, then the Server version MUST be named `+foo-server.conf+`. -* If the configuration will be symlinked in place, the product-specific configuration file MUST be located in an appropriate part of the /etc hierarchy. The divergent config file MUST be specified as `+%config(noreplace)+` in %files as per the usual /etc packaging guidelines. -* If the configuration will be copied in place, the product-specific configuration file MUST be located in an appropriate part of the /usr/share hierarchy. The divergent config file MUST be specified as a normal file in the %files section. +* For each Product requiring a unique default configuration, + the packager MUST provide a copy of the default configuration file, + modified as appropriate for the specific product. +* The product-specific configuration file + MUST be named based on the package's normal naming scheme, + with the main part of the name being suffixed by a dash + followed by the name of the product. + For example, if the package normally uses `+foo.conf+`, + then the Server version MUST be named `+foo-server.conf+`. +* If the configuration will be symlinked in place, + the product-specific configuration file + MUST be located in an appropriate part of the /etc hierarchy. + The divergent config file + MUST be specified as `+%config(noreplace)+` in %files + as per the usual /etc packaging guidelines. +* If the configuration will be copied in place, + the product-specific configuration file + MUST be located in an appropriate part of the /usr/share hierarchy. + The divergent config file + MUST be specified as a normal file in the %files section. === Applying Configuration -In order to apply the configuration, the packager MUST implement a mechanism in the `+%posttrans+` section of the specfile that behaves as follows: +In order to apply the configuration, +the packager MUST implement a mechanism +in the `+%posttrans+` section of the specfile that behaves as follows: -* It MUST first check whether the final config file already exists. If so, the script MUST make no changes. +* It MUST first check whether the final config file already exists. + If so, the script MUST make no changes. .... %posttrans @@ -35,7 +75,15 @@ if [ ! -e %{_sysconfdir}/foo/foo.conf ]; then fi .... -* Then it MUST use the value of the Fedora `+VARIANT_ID+` to symlink or copy one of the divergent config files (or the default) to the final config file location. It will get this value by importing the contents of /etc/os-release as shell values. Known values of this field at the time of this writing are "atomichost", "cloud", "server" and "workstation". For more detail, see https://www.freedesktop.org/software/systemd/man/os-release.html#VARIANT_ID=[the os-release(5) man page]. +* Then it MUST use the value of the Fedora `+VARIANT_ID+` + to symlink or copy one of the divergent config files + (or the default) to the final config file location. + It will get this value + by importing the contents of /etc/os-release as shell values. + Known values of this field at the time of this writing are + "atomichost", "cloud", "server" and "workstation". + For more detail, see + https://www.freedesktop.org/software/systemd/man/os-release.html#VARIANT_ID=[the os-release(5) man page]. .... . /etc/os-release || : @@ -49,13 +97,17 @@ fi esac .... -* Lastly, the final config file location MUST be listed in the %files section with %ghost: +* Lastly, the final config file location + MUST be listed in the %files section with %ghost: .... %ghost %config(noreplace) %{_sysconfdir}/foo/foo.conf .... -* For tracking purposes, the package providing the various configuration files MUST also contain a virtual Provides: for each variant configuration that may be applied: +* For tracking purposes, + the package providing the various configuration files + MUST also contain a virtual Provides: + for each variant configuration that may be applied: .... Provides: variant_config(Atomic.host) @@ -66,7 +118,10 @@ Provides: variant_config(Workstation) === Example (firewalld) -We will assume for the sake of demonstration that firewalld will need a custom configuration for Fedora Server and Fedora Workstation, but that Fedora Cloud will not require any changes from the global default. +We will assume for the sake of demonstration +that firewalld will need a custom configuration +for Fedora Server and Fedora Workstation, +but that Fedora Cloud will not require any changes from the global default. .... ... From 20c714a93ee5dee2501fedb42b3f1cb8a7b1e603 Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Jun 09 2023 01:52:14 +0000 Subject: [PATCH 2/2] Per-Product Configuration: syntax/markup fixes - Set a title for the page (previously loaded as "Untitled") - Enable syntax highlighting in specfile code blocks - backslash-continue & wrap very long specfile lines - Add inline code-literal fencing around body text uses of filesystem paths and filenames, specfile directives, etc. - Attach code blocks to bulleted list items as child elements, where appropriate --- diff --git a/guidelines/modules/ROOT/pages/Per-Product_Configuration.adoc b/guidelines/modules/ROOT/pages/Per-Product_Configuration.adoc index 62de955..1be3b02 100644 --- a/guidelines/modules/ROOT/pages/Per-Product_Configuration.adoc +++ b/guidelines/modules/ROOT/pages/Per-Product_Configuration.adoc @@ -1,3 +1,5 @@ += Per-product Configuration Packaging + In the Fedora.next world, we have a set of curated Fedora Products as well as the availability of classic Fedora. Historically, we have maintained a single set of configuration defaults @@ -11,9 +13,7 @@ for whichever Product on which they are installed, while also avoiding situations where users would have some packages installed with one Product's defaults and some packages with another. -== Per-product Configuration Packaging - -=== Requirements +== Requirements * All packages MUST have a global default configuration. This configuration will be used @@ -26,17 +26,18 @@ with one Product's defaults and some packages with another. * Any package that requires a configuration that differs between Products MUST obtain permission from that Product's Working Group before packaging it. -=== Global Default Configuration +== Global Default Configuration * The global default configuration MUST be provided by the package that requires it. * The global default configuration MUST be named based on the package's normal naming scheme, with the main part of the name being suffixed by -default. - For example, if the package normally uses foo.conf, - then the global default configuration MUST be named foo-default.conf + For example, if the package normally uses `+foo.conf+`, + then the global default configuration + MUST be named `+foo-default.conf+`. -=== Per-Product Default Configuration +== Per-Product Default Configuration * For each Product requiring a unique default configuration, the packager MUST provide a copy of the default configuration file, @@ -49,17 +50,17 @@ with one Product's defaults and some packages with another. then the Server version MUST be named `+foo-server.conf+`. * If the configuration will be symlinked in place, the product-specific configuration file - MUST be located in an appropriate part of the /etc hierarchy. + MUST be located in an appropriate part of the `+/etc+` hierarchy. The divergent config file - MUST be specified as `+%config(noreplace)+` in %files - as per the usual /etc packaging guidelines. + MUST be specified as `+%config(noreplace)+` in `+%files+` + as per the usual `+/etc+` packaging guidelines. * If the configuration will be copied in place, the product-specific configuration file - MUST be located in an appropriate part of the /usr/share hierarchy. + MUST be located in an appropriate part of the `+/usr/share+` hierarchy. The divergent config file - MUST be specified as a normal file in the %files section. + MUST be specified as a normal file in the `+%files+` section. -=== Applying Configuration +== Applying Configuration In order to apply the configuration, the packager MUST implement a mechanism @@ -67,63 +68,68 @@ in the `+%posttrans+` section of the specfile that behaves as follows: * It MUST first check whether the final config file already exists. If so, the script MUST make no changes. - -.... ++ +[source, rpm-spec] +---- %posttrans if [ ! -e %{_sysconfdir}/foo/foo.conf ]; then ... fi -.... +---- * Then it MUST use the value of the Fedora `+VARIANT_ID+` to symlink or copy one of the divergent config files (or the default) to the final config file location. It will get this value - by importing the contents of /etc/os-release as shell values. + by importing the contents of `+/etc/os-release+` as shell values. Known values of this field at the time of this writing are "atomichost", "cloud", "server" and "workstation". For more detail, see https://www.freedesktop.org/software/systemd/man/os-release.html#VARIANT_ID=[the os-release(5) man page]. - -.... - . /etc/os-release || : - case "$VARIANT_ID" in - server) - ln -sf foo-server.conf %{_sysconfdir}/foo/foo.conf || : - ;; - *) - ln -sf foo-default.conf %{_sysconfdir}/foo/foo.conf || : - ;; - esac -.... ++ +[source, rpm-spec] +---- +. /etc/os-release || : +case "$VARIANT_ID" in + server) + ln -sf foo-server.conf %{_sysconfdir}/foo/foo.conf || : + ;; + *) + ln -sf foo-default.conf %{_sysconfdir}/foo/foo.conf || : + ;; + esac +---- * Lastly, the final config file location - MUST be listed in the %files section with %ghost: - -.... + MUST be listed in the `+%files+` section with `+%ghost+`: ++ +[source, rpm-spec] +---- %ghost %config(noreplace) %{_sysconfdir}/foo/foo.conf -.... +---- * For tracking purposes, the package providing the various configuration files - MUST also contain a virtual Provides: + MUST also contain a virtual `+Provides:+` for each variant configuration that may be applied: - -.... ++ +[source, rpm-spec] +---- Provides: variant_config(Atomic.host) Provides: variant_config(Cloud) Provides: variant_config(Server) Provides: variant_config(Workstation) -.... +---- -=== Example (firewalld) +== Example (firewalld) We will assume for the sake of demonstration that firewalld will need a custom configuration for Fedora Server and Fedora Workstation, but that Fedora Cloud will not require any changes from the global default. -.... +[source, rpm-spec] +---- ... Provides: variant_config(Server) Provides: variant_config(Workstation) @@ -140,16 +146,19 @@ if [ ! -e %{_sysconfdir}/firewalld/firewalld.conf ]; then case "$VARIANT_ID" in server) ln -sf firewalld-server.conf %{_sysconfdir}/firewalld/firewalld.conf || : - ln -sf org.fedoraproject.FirewallD1.server.policy %{_datadir}/polkit-1/actions/org.fedoraproject.FirewallD1.policy || : + ln -sf org.fedoraproject.FirewallD1.server.policy \ + %{_datadir}/polkit-1/actions/org.fedoraproject.FirewallD1.policy || : ;; workstation) ln -sf firewalld-workstation.conf %{_sysconfdir}/firewalld/firewalld.conf || : - ln -sf org.fedoraproject.FirewallD1.desktop.policy %{_datadir}/polkit-1/actions/org.fedoraproject.FirewallD1.policy || : + ln -sf org.fedoraproject.FirewallD1.desktop.policy \ + %{_datadir}/polkit-1/actions/org.fedoraproject.FirewallD1.policy || : ;; *) ln -sf firewalld-default.conf %{_sysconfdir}/firewalld/firewalld.conf || : # The default firewall policy will be the same as Server - ln -sf org.fedoraproject.FirewallD1.server.policy %{_datadir}/polkit-1/actions/org.fedoraproject.FirewallD1.policy || : + ln -sf org.fedoraproject.FirewallD1.server.policy \ + %{_datadir}/polkit-1/actions/org.fedoraproject.FirewallD1.policy || : ;; esac fi @@ -167,4 +176,4 @@ fi %ghost %{_datadir}/polkit-1/actions/org.fedoraproject.FirewallD1.policy %{_datadir}/polkit-1/actions/org.fedoraproject.FirewallD1.desktop.policy %{_datadir}/polkit-1/actions/org.fedoraproject.FirewallD1.server.policy -.... +----