Guidelines and HOWTOs/AppStream: Difference between revisions

Revision as of 08:44, 29 November 2016

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

Checklist

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
Create org.kde.foo.appdata.xml in your source tree
Paste the template you can find below into that file
Make sure you replaced all place holders from the template
Take some screenshots and put them in the git repo kde:websites/product-screenshots (note the readme)
Add your screenshots to the appdata.xml file.

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

Validate your appdata using the appstreamcli helper
```
appstreamcli validate org.kde.foo.appdata.xml
```

Validate your installed tree using the helper in your build directory

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

If all looks good commit and push
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/
      </image>
    </screenshot>
  </screenshots>
  <provides>
    <binary>$YOURBINARYNAME!</binary>
  </provides>
  <project_group>KDE</project_group>
</component>

@@ Line 10: / Line 10: @@
 # Paste the template you can find below into that file
 # Make sure you replaced all place holders from the template
+# Take some screenshots and put them in the git repo [https://phabricator.kde.org/source/websites-product-screenshots/ kde:websites/product-screenshots] (note the readme)
+# Add your screenshots to the appdata.xml file.
 # Install the file via CMake (KDE_INSTALL_METAINFODIR is defined by KDEInstallDirs from extra-cmake-modules) {{Input|<syntaxhighlight lang="cmake" line>
 install(FILES org.kde.foo.appdata.xml DESTINATION ${KDE_INSTALL_METAINFODIR})
@@ Line 45: / Line 47: @@
        <image>
          https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-screenshots
-         Central hosting is still being sorted out, poke sitter@kde.org for more info.
+         Central hosting at https://phabricator.kde.org/source/websites-product-screenshots/
        </image>
      </screenshot>