os-release: Introduce experiment RELEASE_TYPE

This is for experimental builds of the OS made to test some specific WIP
feature.

For example, let's say the distro in question is Asahi Linux and Apple
just released the M3 SoC. The Asahi developers will start porting to the
M3, and will quickly generate builds of Asahi Linux that can technically
boot but aren't ready for any kind of daily use. These images are marked
as experimental, and can be shared among the developers. If a user
somehow stumbles upon one of these images and tries to install it,
they'll be warned that they're about to install an experimental Apple M3
port of Asahi Linux. Eventually, once the Asahi developers think that
their M3 port is ready for a wider audience, they can merge it into the
mainline Asahi repos, where it will be distributed through the usual
nightly CI builds (where RELEASE_TYPE=pre-release; M3 support is no
longer experimental).

1 files changed, 43 insertions, 0 deletions

diff --git a/man/os-release.xml b/man/os-release.xml
index 32edc088df..28384d352a 100644
--- a/man/os-release.xml
+++ b/man/os-release.xml
@@ -341,6 +341,8 @@
           <literal>pre-release</literal> is for unstable versions of the system, unsuitable for production
           use, such as alpha, beta, or rolling unstable releases. Examples include Fedora Rawhide, Debian
           Testing, Fedora 40 Beta, and GNOME OS Nightly.
+          <literal>experiment</literal> is for experimental builds of the system, created specifically to
+          test some work-in-progress feature. This is meant to be used in combination with <varname>EXPERIMENT=</varname>.
           If unset, or an unknown value, assume that the release is <literal>stable</literal>.</para>
 
           <para>Examples: <literal>RELEASE_TYPE=pre-release</literal>, <literal>RELEASE_TYPE=lts</literal>.
@@ -466,6 +468,47 @@
 
           <xi:include href="version-info.xml" xpointer="v254"/></listitem>
         </varlistentry>
+        <varlistentry>
+          <term><varname>EXPERIMENT=</varname></term>
+
+          <listitem><para>A human-presentable description of what makes this build of the OS experimental.
+          This field is optional. The <varname>RELEASE_TYPE</varname> field should be set to <literal>experiment</literal>
+          if this field is set, otherwise clients should ignore this field.</para>
+
+          <para>This description is intended to be exposed at system installation time, or in "About this system" UIs,
+          to warn the user that they're installing/running an experimental build of the OS. If <varname>RELEASE_TYPE</varname>
+          is <literal>experiment</literal> but this field is unset, the UI should still warn the user, but it
+          will be unable to explain what exactly is experimental about the current build of the OS.</para>
+
+          <para>Examples: <literal>EXPERIMENT="Switch to DNF5"</literal> for an experimental build of Fedora
+          Linux made to test DNF5, <literal>EXPERIMENT="Port to Apple M3 chip"</literal> for experimental
+          builds of Asahi Linux ported to the Apple M3 SoC,
+          <literal>EXPERIMENT="Mutter !1441: Dynamic triple/double buffering (v4)"</literal> for builds of GNOME
+          OS created by Mutter's CI for merge request !1441.</para>
+
+          <xi:include href="version-info.xml" xpointer="v257"/></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><varname>EXPERIMENT_URL=</varname></term>
+
+          <listitem><para>The main informational page about what makes the current OS build experimental, where users
+          can learn more about the experiment's status and potentially leave feedback. This field is optional. The
+          <varname>EXPERIMENT=</varname> field should be set if this one is, although clients must be robust against
+          either field not being set.</para>
+
+          <para>The value should be in <ulink
+          url="https://tools.ietf.org/html/rfc3986">RFC3986 format</ulink>, and should be
+          <literal>http:</literal> or <literal>https:</literal> URLs. Only one URL shall be listed in the
+          setting.</para>
+
+          <para>Examples, corresponding to the examples above in <varname>EXPERIMENT=</varname>:
+          <literal>EXPERIMENT_URL="https://fedoraproject.org/wiki/Changes/SwitchToDnf5"</literal>,
+          <literal>EXPERIMENT_URL="https://github.com/AsahiLinux/docs/wiki/M3-Series-Feature-Support"</literal>,
+          <literal>EXPERIMENT_URL="https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/1441"</literal>.</para>
+
+          <xi:include href="version-info.xml" xpointer="v257"/></listitem>
+        </varlistentry>
       </variablelist>
     </refsect2>