# For upstream projects providing addons

## Introduction

TODO: write short intro

## Example file

The file should contain something like this:

    <?xml version="1.0" encoding="UTF-8"?>
    <component type="addon">
      <id>gedit-bookmarks</id>
      <extends>gedit.desktop</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>CC0-1.0</metadata_license>
      <project_license>GPL-2.0+</project_license>
    </component>

## 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 () and an addon-component ().

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

<name/>

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

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

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

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

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

<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. Take a look at 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 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 tag for more details on how to use this tag.