For upstream projects providing addons | AppStream

AppStream › Metadata Quickstart › For upstream projects providing addons

AppStream

Navigation←→

5.2 For upstream projects providing addons #

5.2.1 Introduction #

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 addon 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.

Software which provides addons can ship one or more files in /usr/share/metainfo/%{id}.metainfo.xml.

Tip

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 freedesktop.org/software/appstream/metainfocreator (https://www.freedesktop.org/software/appstream/metainfocreator/#/).

5.2.2 Example file #

The file should contain something like this:

<?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>

5.2.3 Metadata file contents #

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 (Section 2.1.3, “XML Specification”) and an addon component (Section 2.7.3, “File specification”).

<id/>

For addons, there is no strict rule for the component-ID. You should just ensure that you pick a unique name.

It is highly recommended to apply a application_name-plugin_name naming scheme for your addon-id.

<extends/>

This tag is refers to the ID of the component this addon is extending. For desktop applications, this is usually the name of their .desktop file.

This tag is described in detail for addon components at <extends/>.

<name/>

Each addon component needs a <name/> tag, giving the addon a human-readable name.

Note

Don't put the application name you are extending in the <name/> - so you want to use Bookmarks rather than GEdit Bookmarks

<summary/>

The <summary/> tag follows the basic structure of a <summary/> as described in the specification. It is a required tag for an addon component.

Some useful hints for finding a good addon summary:

Don't put the application name you are extending in the <summary/> - so you want to use Easy document navigation with bookmarks rather than Easy document navigation with bookmarks in GEdit.
Don't use long or short descriptions. Ideally <summmary/> should be less than 101 and more than 8.

<url/>

It is recommended to include links of types homepage and bugtracker. You can omit the <url/> if it's the same as the upstream project.

Links of type homepage should be a link to the upstream homepage for the addon.

Links of type bugtracker should be a link to the upstream bugtracker.

Note

It is highly recommended to be a link to the upstream bugzilla with filed component and product.

Warning

It might be necessary to escape URLs. For example replacing of & with &.

For other possible values, take a look at the tag's description in <url/>.

<metadata_license/>

The <metadata_license/> 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:

The license codes correspond to the identifiers found at the SPDX OpenSource License Registry (http://spdx.org/licenses/). Take a look at <metadata_license/> for more details about this tag.

<project_license/>

The <project_license/> tag is indicating the license(s) this addon is released under. Take a look at the specification of the <project_license/> tag for details on how to properly use it.

<update_contact/>

You might want to include an update-contact email address. Take a look at the specification of the <update_contact/> tag for more details on how to use this tag.