Guidelines and HOWTOs/AppStream

From KDE Community Wiki

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

Checklist

  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 whenver you may need that. It's basically your file name.
    2. If you have a dbus service ... make sure that your dbus 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 or you need to use KAboutData::setDesktopFileName() to set the desktop file name you are using
  2. Create org.kde.foo.appdata.xml in your source tree
  3. Paste the template you can find below 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)
  6. Add 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

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

<?xml version="1.0" encoding="utf-8"?>
<component type="desktop">
  <id>org.kde.$NAME.desktop</id>
  <metadata_license>CC0-1.0</metadata_license>
  <project_license> https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-metadata_license </project_license>
  <name>$NAME</name>
  <summary> https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-summary </summary>
  <description>
    <p> https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-description </p>
  </description>
  <url type="homepage">https://www.kde.org</url>
  <url type="bugtracker">https://bugs.kde.org</url>
  <url type="donation">https://www.kde.org/community/donations</url>
  <screenshots>
    <screenshot type="default">
      <image>
        https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-screenshots
        Central hosting at https://phabricator.kde.org/source/websites-product-screenshots/
        Central URL https://cdn.kde.org/screenshots/...
      </image>
    </screenshot>
  </screenshots>
  <provides>
    <binary>$YOURBINARYNAME!</binary>
  </provides>
  <project_group>KDE</project_group>
</component>