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.

Metainfo Generator

Appstream has its own web tool to generate a new appstream file which might be useful: https://www.freedesktop.org/software/appstream/metainfocreator

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>
  <developer id="org.kde">
    <name translate="no">KDE</name>
  </developer>
  <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://invent.kde.org/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>

Promotion best practices

As Appstream appdata determines what is shown in application stores such as Discover, your application should be not only concise, but also attractive so as to make users want to install it. Your .appdata.xml file should contain the following information:

Very brief summary to entice user into installing it.

Short/medium-length description of what the application does and how it is useful for the user. Features:

  • Feature 1;
  • Feature 2;
  • Feature 3;
  • Feature n.

The <summary> should be one line in size as to make it concise, and it should primarily describe what the application does, not what it is. For such, the best way is to begin the summary with a verb. In the KBackup example displayed here: Create backups as .tar files to a local folder or remote URL.

It is possible to avoid using a verb at the beginning when the mere description of what it is already describes what it does (for instance, Lskat's "German card game Skat for two players"), or when describing what it does immediately after telling the user what it is (such as Amarok's "A powerful music player that lets you rediscover your music"). Of course, you can always get creative with that! Don't feel restricted to these guidelines.

More importantly, generally avoid filler terms/buzzwords such as "simple", "user-friendly", "advanced"; jargon such as "front-end", "conflict resolution"; and acronyms, unless they're really necessary.

The <description> lets you have more freedom with how to phrase things, as there is more space. However, the principles mentioned above should be taken into account, and unless your application has a very specific target audience, strive for clarity rather than elegance or brevity. Your user should know exactly what your application does after reading your description even if it takes a few words more, and they should find that it fits their needs.

Remember to always order your feature list with an unordered list <ul> <li>, and you as a developer don't need to care about tags used for localization such as <p xml:lang="de">. Our localization infrastructure extracts your appstream data, our translators translate it, and the translations get imported back into the .appdata.xml file for you.

Now, here's a hypothetical example based on KBackup: 

<summary>Create backups as .tar files to a local folder or remote URL</summary>
<description>
  <p>KBackup lets you back up your data straight away with minimum hassle.</p>
  <p>It's designed to require as little clicks as possible.</p>
  <p>Features:</p>
  <ul>
    <li>Using profile files with definitions for Folders and files to be included or excluded from the backup</li>
    <li>The backup target can be either a locally mounted device like a ZIP drive, USB stick, etc. or any remote URL</li>
  </ul>
</description>

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

These tags 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 the name of a Matrix channel.

Example: <value key="KDE::matrix">#kdevelop:kde.org</value>


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

The <value key="KDE::irc"/> tag is an optional tag containing the name of the IRC channel available on the official IRC network used by the KDE community.

Example: <value key="KDE::irc">#kdevelop</value>


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

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

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


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

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

Example: <value key="KDE::mailinglist">[email protected]</value>


<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 (e.g. [email protected] for the users and [email protected] for those involved in Kontact development).

Example: <value key="KDE::mailinglist-devel">[email protected]</value>

Retrieved from "https://community.kde.org/index.php?title=Guidelines_and_HOWTOs/AppStream&oldid=100758"