spec: Specify a metadata format for external release descriptions

CC: #354
ximion · Jan 4, 2023 · 894da43 · 894da43
1 parent 139ed0f
commit 894da43
Show file tree

Hide file tree

Showing 3 changed files with 71 additions and 4 deletions.
diff --git a/docs/xml/collection-xmldata.xml b/docs/xml/collection-xmldata.xml
@@ -505,8 +505,7 @@
 				<term>&lt;releases/&gt;</term>
 				<listitem>
 					<para>
-						The <literal>releases</literal> tag and its <literal>release</literal> children are structured as described in <xref linkend="tag-releases"/>, with the
-						additional requirement that releases must be sorted in a latest-to-oldest order.
+						The <literal>releases</literal> tag and its <literal>release</literal> children are structured as described in <xref linkend="sect-Metadata-Releases"/>.
 					</para>
 					<para>
 						Each <literal>release</literal> tag may have a <literal>description</literal> tag as child, containing a brief description of what is new in the release.
@@ -517,6 +516,11 @@
 						It may also convert ISO 8601 <literal>date</literal> properties of the metainfo file into an UNIX timestamp <literal>timestamp</literal> property.
 						It should avoid generating metadata containing both properties on a <literal>release</literal> tag.
 					</para>
+					<para>
+						If a <xref linkend="tag-releases"/> tag in a metainfo file references an <literal>external</literal> release description, the release description should
+						be read either from the release file provided locally, or, if possible and provided, be downloaded from the URL referenced in the component's <literal>releases</literal>
+						tag.
+					</para>
 					<para>
 						Example for a valid releases tag:
 					</para>

diff --git a/docs/xml/metainfo-component.xml b/docs/xml/metainfo-component.xml
@@ -499,11 +499,53 @@
 		<term>&lt;releases/&gt;</term>
 		<listitem>
 			<para>
-				The <code><![CDATA[<releases>]]></code> tag contains multiple <literal>release</literal> children that contain
-				metadata about releases made for this software component.
+				The <code><![CDATA[<releases>]]></code> tag contains multiple <literal>release</literal> children that
+				themselves contain metadata about releases made for this software component.
 				The release information XML is described in-depth in <xref linkend="sect-Metadata-Releases"/>,
 				examples for a valid <literal>releases</literal> tag with artifacts are also provided there.
 			</para>
+			<para>
+				Release information can be embedded in the component's metainfo file, following the XML
+				description outlined in <xref linkend="sect-Metadata-Releases"/>. Alternatively, it can also
+				be split into its own metadata file as described in that section. In case of external metadata,
+				a <literal>releases</literal> tag must still be present in the component's metainfo file, and
+				must have a <literal>type</literal> property set to value <code>external</code> (if the <literal>type</literal>
+				property is missing, a value of <code>embedded</code> is implicitly assumed for it).
+			</para>
+			<para>
+				In case of external metadata, the <literal>releases</literal> tag may also have an <literal>url</literal>
+				property linking to a web location where the relesse XML can be found and updated separately from the
+				main component metadata. An <literal>url</literal> property must not be present without <literal>type</literal>
+				set to <code>external</code>.
+			</para>
+			<para>
+				Only HTTPS links are allowed for the web URL, and any <literal>artifact</literal> defined in a
+				release description from an external website should not be trusted without further verification, as external
+				release information can currently not be signed.
+			</para>
+			<para>
+				AppStream catalog metadata generators may choose to update the locally provided release information with the data from
+				the web location provided by the URL in <literal>url</literal>.
+				This allow projects to complete release localization after a release was made, or include further information that was
+				not yet available directly at release time.
+				The generated catalog XML data must be complete and must not contain references to external release information.
+			</para>
+			<para>
+				Example for a <literal>releases</literal> block that points to an external metadata file:
+			</para>
+			<programlisting language="XML"><![CDATA[<releases external="yes" url="https://example.org/releases/org.example.myapp.releases.xml" />]]></programlisting>
+			<important>
+				<title>Local Release Data</title>
+				<para>
+					Please note that even if release data is external and also provided on a remote location, it also <emphasis>must</emphasis> be
+					available locally, installed as a file into <filename>/usr/share/metainfo/releases/%{cid}.releases.xml</filename>.
+					The local file may not contain all information (for example it may not have a complete release description or all translations),
+					but basic data such as the released versions and their release dates should be present.
+				</para>
+				<para>
+					It is an error to reference an external release data file, but not provide a local copy of it.
+				</para>
+			</important>
 		</listitem>
 		</varlistentry>
 

diff --git a/docs/xml/releases-data.xml b/docs/xml/releases-data.xml
@@ -13,6 +13,27 @@
 			This section documents the <xref linkend="tag-releases"/> tag that can be part of a <literal>component</literal> to provide
 			information about releases made for the respective component.
 		</para>
+		<para>
+			Alternatively to being embedded in a component metainfo file, the data may also be split into a dedicated XML file to be updated separately.
+		</para>
+	</section>
+
+	<section id="spec-releases-location">
+		<title>Locations</title>
+
+		<para>
+			Release data may be present directly in a component metainfo file, but also optionally be split out into an external metadata file.
+		</para>
+		<para>
+			If the <literal>releases</literal> XML is part of a metainfo file, it is embedded into it following the semantics described in the document.
+		</para>
+		<para>
+			If the <literal>releases</literal> XML is external, the metainfo file must contain a <xref linkend="tag-releases"/> tag with the <literal>type</literal>
+			property set to <code>external</code> as described for component XML.
+			The data described in this section is placed in a separate XML file with <literal>releases</literal> being its root node.
+			The file must be installed as <filename>/usr/share/metainfo/releases/%{cid}.releases.xml</filename>, where <code>cid</code> is the component ID of the component
+			the release information belongs to.
+		</para>
 	</section>
 
 	<section id="spec-releases-example">