<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "AppStream.ent">
%BOOK_ENTITIES;
]>

<section id="sect-Quickstart-Addons">
	<title>For upstream projects providing addons</title>

	<section id="qsr-addon-introduction">
		<title>Introduction</title>
		<para>
			Some software installed on the system is extensible via addons. To allow the user to install addons for
			software that is already available on the system, AppStream defines an <literal>addon</literal> component type.
			Software centers will usually group these components together with their host component and display them for installation.

			Extensible software may also access the AppStream data pool provided by the distribution or other software source directly,
			to offer installing missing addons from within the application.
		</para>
		<para>
			Software which provides addons can ship one or more files in <filename>/usr/share/metainfo/%{id}.metainfo.xml</filename>.
		</para>
		<tip>
			<para>
				To get you started quickly, the AppStream project provides a web-based form to quickly generate valid metainfo XML for some of the most
				common use cases. Check it out on <ulink url="https://www.freedesktop.org/software/appstream/metainfocreator/#/">freedesktop.org/software/appstream/metainfocreator</ulink>.
			</para>
		</tip>
	</section>

	<section id="qsr-addon-example">
		<title>Example file</title>
		<para>
			The file should contain something like this:
		</para>
		<programlisting language="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<component type="addon">
  <id>org.gnome.gedit.gedit_bookmarks</id>
  <extends>org.gnome.gedit</extends>
  <name>Bookmarks</name>
  <summary>Easy document navigation with bookmarks</summary>
  <url type="homepage">https://wiki.gnome.org/Apps/Gedit/ShippedPlugins</url>
  <url type="bugtracker">https://bugzilla.gnome.org/enter_bug.cgi?product=gedit&amp;component=Plugins</url>
  <metadata_license>FSFAP</metadata_license>
  <project_license>GPL-2.0+</project_license>
</component>]]></programlisting>
	</section>

	<section id="qsr-addon-content">
		<title>Metadata file contents</title>
		<para>
			This is a list of tags you might want to define for your application. For a full list of possible tags, take a look at
			the definition of a generic component (<xref linkend="spec-component-filespec"/>) and an addon component (<xref linkend="spec-addondata-filespec"/>).
		</para>

		<variablelist>
			<varlistentry>
			<term>&lt;id/&gt;</term>
			<listitem>
				<para>
					For addons, there is no strict rule for the component-ID. You should just ensure that you pick a unique name.
				</para>
				<para>
					It is highly recommended to apply a <code>application_name-plugin_name</code> naming scheme for your addon-id.
				</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term>&lt;extends/&gt;</term>
			<listitem>
				<para>
					This tag is refers to the ID of the component this addon is extending. For desktop applications, this is usually the name of their <filename>.desktop</filename> file.
				</para>
				<para>
					This tag is described in detail for addon components at <xref linkend="tag-extends"/>.
				</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term>&lt;name/&gt;</term>
			<listitem>
				<para>
					Each addon component needs a <literal>&lt;name/&gt;</literal> tag, giving the addon a human-readable name.
				</para>
				<note>
					<para>
						Don't put the application name you are extending in the <literal>&lt;name/&gt;</literal> - so you want to use <code>Bookmarks</code> rather than <code>GEdit Bookmarks</code>
					</para>
				</note>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term>&lt;summary/&gt;</term>
			<listitem>
				<para>
					The <literal>&lt;summary/&gt;</literal> tag follows the basic structure of a <xref linkend="tag-summary"/> as described in the specification. It is a required tag for an addon component.
				</para>
				<para>
					Some useful hints for finding a good addon summary:
				</para>
				<itemizedlist>
					<listitem>
						<para>
							Don't put the application name you are extending in the <literal>&lt;summary/&gt;</literal> - so you want to use <code>Easy document navigation with bookmarks</code>
							rather than <code>Easy document navigation with bookmarks in GEdit</code>.
						</para>
					</listitem>
					<listitem>
						<para>
							Don't use long or short descriptions.
							Ideally <literal>&lt;summmary/&gt;</literal> should be less than <code>101</code> and more than <code>8</code>.
						</para>
					</listitem>
				</itemizedlist>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term>&lt;url/&gt;</term>
			<listitem>
				<para>
					It is recommended to include links of types <code>homepage</code> and <code>bugtracker</code>.
					You can omit the <literal>&lt;url/&gt;</literal> if it's the same as the upstream project.
				</para>
				<para>
					Links of type <code>homepage</code> should be a link to the upstream homepage for the addon.
				</para>
				<para>
					Links of type <code>bugtracker</code> should be a link to the upstream bugtracker.
				</para>
				<note>
					<para>
						It is highly recommended to be a link to the upstream bugzilla with filed component and product.
					</para>
				</note>
				<warning>
					<para>
						It might be necessary to escape URLs. For example
						replacing of <code>&amp;</code> with <code>&amp;amp;</code>.
					</para>
				</warning>
				<para>
					For other possible values, take a look at the tag's description in <xref linkend="tag-url"/>.
				</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term>&lt;metadata_license/&gt;</term>
			<listitem>
				<para>
					The <code>&lt;metadata_license/&gt;</code> tag is indicating the content license that you are releasing the one
					metadata file as. This is not typically the same as the project license. By ommitting the license value would
					probably mean your data would not be incorporated into the distribution metadata.
					Permissible license codes include:
				</para>
				<para>
					The license codes correspond to the identifiers found at the <ulink url="http://spdx.org/licenses/">SPDX OpenSource License Registry</ulink>.
					Take a look at <xref linkend="tag-metadata_license"/> for more details about this tag.
				</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term>&lt;project_license/&gt;</term>
			<listitem>
				<para>
					The <literal>&lt;project_license/&gt;</literal> tag is indicating the license(s) this addon is released under.
					Take a look at the specification of the <xref linkend="tag-project_license"/> tag for details on how to properly use it.
				</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term>&lt;update_contact/&gt;</term>
			<listitem>
				<para>
					You might want to include an update-contact email address. Take a look at the specification of the <xref linkend="tag-update_contact"/> tag
					for more details on how to use this tag.
				</para>
			</listitem>
			</varlistentry>

		</variablelist>
	</section>

</section>
