Guidelines and HOWTOs/AppStream

Quick guide on how to AppStream your app. For a more in-depth overview hop on over to Techbase.

Checklist

Assuming your software is named "foo"...

1. Make sure your desktop file is reverse-domain-notation i.e. org.kde.foo
   1. Your desktop file should be org.kde.foo.desktop. This is also your desktop-id, so whenever you may need that. It's basically your file name.
   2. If you have a D-Bus service ... make sure that your D-Bus service name matches this or change your desktop file to match the service address (whichever seems more appropriate)
   3. The name part 'foo' MUST be the name of your binary. If it should be different you need to either use KAboutData::setDesktopFileName() or, if not using KAboutData, QGuiApplication::setDesktopFileName() to set the desktop file name you are using for the app's runtime metadata
2. Create a file org.kde.foo.appdata.xml in your source tree
3. Paste the template you can find below (see section Template) into that file
4. Make sure you replaced all place holders from the template
5. Take some screenshots and put them in the git repo kde:websites/product-screenshots (note the README.md)
6. Add the CDN links to your screenshots to the appdata.xml file.
7. Install the file via CMake (KDE_INSTALL_METAINFODIR is defined by KDEInstallDirs from extra-cmake-modules)

   install(FILES org.kde.foo.appdata.xml DESTINATION ${KDE_INSTALL_METAINFODIR})
   

8. Validate your appdata using the appstreamcli helper

   appstreamcli validate org.kde.foo.appdata.xml

9. Validate your installed tree using the helper in your build directory

   make
   make install DESTDIR=root
   appstreamcli validate-tree root
   rm -r root
   

10. If all looks good commit and push
11. If you have any questions submit a review and make sure to subscribe sitter and mak

Template

You can create a template from the Meta Info Creator site or copy from below.

Carefully review all fields and replace all $VARIABLES ($NAME with your application name as seen in the reverse domain notation). Where appropriate the fields have URLs of respective AppStream documentation to help you find out what to put there.

<?xml version="1.0" encoding="utf-8"?>
<component type="desktop-application">
  <id>org.kde.$NAME</id>
  <metadata_license>FSFAP</metadata_license>
  <project_license> see https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-metadata_license </project_license>
  <name>$NAME</name>
  <summary> see https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-summary </summary>
  <description>
    <p> see https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-description </p>
    <p>And see.</p>
    <p>And see:</p>
    <ul>
      <li>this</li>
      <li>that</li>
    </ul>
  </description>
  <url type="homepage">https://www.kde.org</url>
  <url type="bugtracker">https://bugs.kde.org/enter_bug.cgi?format=guided&amp;product=$YOURPRODUCTNAME</url>
  <url type="donation">https://www.kde.org/community/donations/?app=$YOURBINARYNAME</url>
  <launchable type="desktop-id">org.kde.$NAME.desktop recommended, see https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-launchable </launchable>
  <screenshots>
    <screenshot type="default">
      <image>
        see https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-screenshots
        Central hosting for uploading at https://phabricator.kde.org/source/websites-product-screenshots/
        Central URL to use here https://cdn.kde.org/screenshots/...
      </image>
    </screenshot>
  </screenshots>
  <provides>
    <binary>$YOURBINARYNAME</binary>
  </provides>
  <project_group>KDE</project_group>
</component>

Release version numbers and dates

Appstream files can contain release version numbers and dates (other information is possible too such as changelogs but this is not much used in KDE). This gets extracted from git master branch and shown on kde.org/applications.

  <releases>
    <release version="20.04.2" date="2020-06-11"/>
    <release version="20.04.1" date="2020-05-14"/>
    <release version="20.04.0" date="2020-04-23"/>
    <release version="19.12.3" date="2020-03-05"/>
  </releases>

This can be added with the appstream-metainfo-release-update script.

Adding release data has also been added to recent versions of appstreamcli.

See also Application Versioning

KDE customs tags

AppStream allow customs tags (see https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-custom).

Here is a temporary proposal (don't use it yet) for some custom tags that are then displayed in kde.org/applications.

Other operating systems

Use this than your KDE applications is distributed in a third-party store. Please only link to stable release. All these tags are optional.

<value key="KDE::steam"/>

The <value key="KDE::steam"/> tag is an optional tag containing a link to the application page in the Steam Store.

<value key="KDE::windows_store"/>

The <value key="KDE::windows_store"/> tag is an optional tag containing a link to the application page in the Windows Store.

<value key="KDE::fdroid"/>

The <value key="KDE::fdroid"/> tag is an optional tag containing the 'F-Droid' store identifier. For example for KDE Connect, the url is: https://f-droid.org/en/packages/org.kde.kdeconnect_tp/, then the identifier is org.kde.kdeconnect_tp.

<value key="KDE::play_store"/>

The <value key="KDE::play_store"/> tag is an optional tag containing a 'Play Store' store identifier. The tag is probably the same as for the F-Droid identifier. For example for KDE Connect, the url is: https://play.google.com/store/apps/details?id=org.kde.kdeconnect_tp, then the identifier is org.kde.kdeconnect_tp.

<value key="KDE::macos_download"/>

The <value key="KDE::macos_download"/> tag is an optional tag containing a link to a MacOS installer. In case your application is available in macOS App Store, you can use this tag to link to the App Store page.

Communication platforms

<value key="KDE::matrix"/>

The <value key="KDE::matrix"/> tag is an optional tag containing a link to a Matrix channel.

<value key="KDE::irc"/>

The <value key="KDE::irc"/> tag is an optional tag containing a link to an IRC channel available in Freenode.

<value key="KDE::forum"/>

The <value key="KDE::forum"/> tag is an optional tag containing the sub forum id in forum.kde.org.

<value key="KDE::mailinglist"/>

The <value key="KDE::mailinglist"/> tag is an optional tag containing the email address of the mailing-list.

<value key="KDE::mailinglist-devel"/>

The <value key="KDE::mailinglist-devel"/> tag is an optional tag containing the email address of the mailing-list in case there is a separate mailing list for the development team. (ex [email protected] for the users and [email protected] for those involved in Kontact development).