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

You can also add release meta data. Description, announce URL and release artifacts (download installer and binary files) are supported by the kde.org/applications website. For example:

    <release date="2020-06-18" version="4.3.0">
      <description>
        <p>Three months after the release of Krita 4.2.9, we’ve got a major new feature release for you: Krita 4.3.0! We’ve spent the past year not just fixing bugs, even though we fixed over a thousand issues, but have also been busy adding cool new stuff to play with.</p>
        <p>There’s a whole new set of brush presets that evoke watercolor painting. There’s a color mode in the gradient map filter and a brand new palettize filter and a high pass filter. The scripting API has been extended. It’s now possible to adjust the opacity and lightness on colored brush tips separately. You can now create animated brush tips that select brush along multiple dimensions. We’ve made it possible to put the canvas area in a window of its own, so on a multi monitor setup, you can have all the controls on one monitor, and your images on the other. The color selector has had a big update. There’s a new snapshot docker that stores states of your image, and you can switch between those. There’s a brand new magnetic selection tool. Gradients can now be painting as spirals.</p>
      </description>
      <url>https://krita.org/en/item/krita-4-3-0-released/</url>
      <artifacts>
        <artifact type="binary" platform="x86_64-appimage">
          <location>https://download.kde.org/stable/krita/4.3.0/krita-4.3.0-x86_64.appimage</location>
          <checksum type="sha256">488a6c27876612fca710609483a265821c6bb802d24edf1e970a544744f1c75d</checksum>
          <size type="download">210276392</size>
          <bundle type="appimage">krita-4.3.0</bundle>
        </artifact>
        <artifact type="binary" platform="x86_64-appimage">
          <location>https://download.kde.org/stable/krita/4.3.0/gmic_krita_qt-x86_64.appimage</location>
          <checksum type="sha256">11744659641e61d180592851453f2b278ce445ea828067037b57c0af0339571a</checksum>
          <size type="download">32006184</size>
          <bundle type="appimage">gmic_krita_qt-4.3.0</bundle>
        </artifact>
        <artifact type="binary" platform="macOS">
          <location>https://download.kde.org/stable/krita/4.3.0/krita-4.3.0.dmg</location>
          <checksum type="sha256">5a8da4d00dc2678a865a3d4938eba4b1a739fc92ffc700e91eae56b67162ce28</checksum>
          <size type="download">180959904</size>
        </artifact>
        <artifact type="binary" platform="win64">
          <location>https://download.kde.org/stable/krita/4.3.0/krita-x64-4.3.0-setup.exe</location>
          <checksum type="sha256">39346273dfa9397af61f4caf779e2d3d5d59a43d67248bc827b6704a08e9e59f</checksum>
          <size type="download">116765304</size>
        </artifact>
        <artifact type="binary" platform="win32">
          <location>https://download.kde.org/stable/krita/4.3.0/krita-x86-4.3.0-setup.exe</location>
          <checksum type="sha256">15018230d2fd5caa8a3778b1ff88b0582d93255108e1e5f781880d1d5401e9e3</checksum>
          <size type="download">114433288</size>
        </artifact>
        <artifact type="source">
          <location>https://download.kde.org/stable/krita/4.2.9/krita-4.2.9.tar.xz</location>
          <checksum type="sha256">4ef711887dd3ec5f2a1c42a80f2fd0fec1de0d4f3d0147b0efd418ac6e4d7567</checksum>
          <size type="download">170082028</size>
        </artifact>
      </artifacts>
    </release>

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