sysupdate: Support changelogs & appstream metadata

Makes it possible to specify URLs to a changelog and an appstream
catalog XML in the sysupdate.d/*.conf files. This will be passed along
to the clients of systemd-sysupdated, which can then present this data.

1 files changed, 118 insertions, 0 deletions

diff --git a/docs/APPSTREAM_BUNDLE.md b/docs/APPSTREAM_BUNDLE.md
new file mode 100644
index 0000000000..f953e169d0
--- /dev/null
+++ b/docs/APPSTREAM_BUNDLE.md
@@ -0,0 +1,118 @@
+---
+title: Appstream Bundle
+category: Interfaces
+layout: default
+SPDX-License-Identifier: LGPL-2.1-or-later
+---
+
+# Appstream Bundle
+
+NOTE: This document is a work-in-progress.
+
+NOTE: This isn't yet implemented in libappstream and the software centers.
+
+[Appstream catalogs](https://www.freedesktop.org/software/appstream/docs/chap-CatalogData.html)
+are a standardized way to expose metadata about system components, apps, and updates to software
+centers (i.e. GNOME Software and KDE Discover). The `<bundle/>` tag links an appstream component
+to a packaging format. This is used by the software centers to decide which code path (or plugin)
+should handle the component. For instance: components with a `<bundle type="package">...</bundle>`
+will be handled by [PackageKit](https://www.freedesktop.org/software/PackageKit/), and components
+with a `<bundle type="flatpak">...</bundle>` will be handled by [libflatpak](https://docs.flatpak.org/).
+This document will define how to format an appstream component's `<bundle>` tag such that software
+centers will know to manage it using systemd. The following syntax will be supported:
+
+A `type="systemd"` attribute. This tells the software center that it should treat the bundle tag
+as described in this document.
+
+A `class=""` attribute, with the following possible values: `sysupdate`, `extension`, `confext`,
+or `portable`. These correspond to sysupdate components, sysexts, confexts, and portable services
+respectively.
+
+The value of the tag will be used as the name of the image (corresponding to the `class=` attribute).
+So for instance, `<bundle type="systemd" class="extension">foobar</bundle>` corresponds to a sysext
+named "foobar". For `class="sysupdate"`, there is a special case: if the value is empty, then the
+bundle actually refers to the host system.
+
+## Examples
+
+```xml
+<component type="addon">
+	<id>com.example.Devel</id>
+	<extends>com.example.OS</extends>
+	<name>Development Tools</name>
+	<summary>Tools essential to develop Example OS</summary>
+	<provides>
+		<binary>gcc</binary>
+		<binary>g++</binary>
+		<binary>make</binary>
+		<binary>autoconf</binary>
+		<binary>cmake</binary>
+		<binary>meson</binary>
+		<binary>ninja</binary>
+	</provides>
+	<developer_name>Example, inc.</developer_name>
+	<releases>
+		<release version="45" date="2024-01-15" />
+		<release version="44" date="2023-12-08" />
+		<release version="43" date="2023-11-10" />
+	</releases>
+	<bundle type="systemd" class="extension">devel</bundle>
+</component>
+```
+
+defines a sysext named `devel` to be presented by the software center. It will be
+updated via `systemd-sysupdated`'s `extension:devel` target. It will be treated
+as a plugin for the operating system itself.
+
+```xml
+<component merge="append">
+	<id>com.example.OS</id>
+	<releases>
+		<release version="45" date="2024-01-15" urgency="high">
+			<description>
+				<p>This release includes various bug fixes and performance improvements</p>
+			</description>
+		</release>
+	</releases>
+	<bundle type="systemd" class="sysupdate" />
+</component>
+```
+
+extends existing appstream metadata for the host OS with a changelog. It also tells the software
+center that the host OS should be updated using the `host` target for `systemd-sysupdated`.
+
+```xml
+<component type="service">
+	<id>com.example.Foobar</id>
+	<name>Foobar Service</name>
+	<summary>Service that does foo to bar</summary>
+	<icon type="remote">https://example.com/products/foobar/logo.svg</icon>
+	<url type="homepage">https://example.com/products/foobar</url>
+	<provides>
+		<dbus type="system">com.example.Foobar</dbus>
+	</provides>
+	<developer_name>Example, inc.</developer_name>
+	<releases>
+		<release version="1.0.1" date="2024-02-16" urgency="critical">
+			<description>
+				<p>This release fixes a major security vulnerability. Please update ASAP.</p>
+			</description>
+			<issues>
+				<issue type="cve">CVE-2024-28153</issue>
+			</issues>
+		</release>
+		<release version="1.1-beta" date="2024-01-08" type="development" />
+		<release version="1.0" date="2023-11-23">
+			<description>
+				<p>Initial release!</p>
+			</description>
+		</release>
+	</releases>
+	<bundle type="systemd" class="portable">foobar</bundle>
+</component>
+```
+
+defines a portable service named `foobar` to be presented by the software center. It will be
+updated via `systemd-sysupdated`'s `portable:foobar` target. It will be marked as an
+urgent update. It will be presented to the user with a display name, a description, and
+a custom icon.