Difference between revisions of "Guidelines and HOWTOs/AppStream"

Jump to: navigation, search
m (change proposal)
 
(15 intermediate revisions by 6 users not shown)
Line 1: Line 1:
Quick guide on how to AppStream your app.
+
Quick guide on how to AppStream your app. For a more in-depth overview hop on over to [https://techbase.kde.org/MetaInfo Techbase].
  
Checklist
+
==Checklist==
  
 +
Assuming your software is named "foo"...
 
# Make sure your desktop file is reverse-domain-notation i.e. org.kde.foo
 
# Make sure your desktop file is reverse-domain-notation i.e. org.kde.foo
## 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.
+
## 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.
## 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)
+
## 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)
## The name part 'foo' MUST be the name of your binary or you need to use [https://api.kde.org/frameworks/kcoreaddons/html/classKAboutData.html KAboutData::setDesktopFileName()] to set the desktop file name you are using
+
## The name part 'foo' MUST be the name of your binary. If it should be different you need to either use [https://api.kde.org/frameworks/kcoreaddons/html/classKAboutData.html KAboutData::setDesktopFileName()] or, if not using KAboutData, [https://doc.qt.io/qt-5/qguiapplication.html#desktopFileName-prop QGuiApplication::setDesktopFileName()] to set the desktop file name you are using for the app's runtime metadata
# Create org.kde.foo.appdata.xml in your source tree
+
# Create a file org.kde.foo.appdata.xml in your source tree
# Paste the template you can find below into that file
+
# Paste the template you can find below (see section [[#Template|Template]]) into that file
 
# Make sure you replaced all place holders from the template
 
# Make sure you replaced all place holders from the template
# Install the file via CMake (KDE_INSTALL_METAINFODIR is defined by KDEInstallDirs from extra-cmake-modules) {{Input|<syntaxhighlight lang="cmake" line>
+
# 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.md)
 +
# Add the CDN links to your screenshots to the appdata.xml file.
 +
# Install the file via CMake (KDE_INSTALL_METAINFODIR is defined by [https://api.kde.org/ecm/kde-module/KDEInstallDirs.html KDEInstallDirs] from extra-cmake-modules) {{Input|<syntaxhighlight lang="cmake" line>
 
install(FILES org.kde.foo.appdata.xml DESTINATION ${KDE_INSTALL_METAINFODIR})
 
install(FILES org.kde.foo.appdata.xml DESTINATION ${KDE_INSTALL_METAINFODIR})
 
</syntaxhighlight>}}
 
</syntaxhighlight>}}
Line 25: Line 28:
 
== Template ==
 
== 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.
+
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.
  
{{Input|<syntaxhighlight lang="xml" line>
+
{{Input|<syntaxhighlight lang="xml">
 
<?xml version="1.0" encoding="utf-8"?>
 
<?xml version="1.0" encoding="utf-8"?>
<component type="desktop">
+
<component type="desktop-application">
   <id>org.kde.$NAME.desktop</id>
+
   <id>org.kde.$NAME</id>
   <metadata_license>CC0-1.0</metadata_license>
+
   <metadata_license>FSFAP</metadata_license>
   <project_license> https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-metadata_license </project_license>
+
   <project_license> see https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-metadata_license </project_license>
 
   <name>$NAME</name>
 
   <name>$NAME</name>
   <summary> https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-summary </summary>
+
   <summary> see https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-summary </summary>
 
   <description>
 
   <description>
     <p> https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-description </p>
+
     <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>
 
   </description>
 
   <url type="homepage">https://www.kde.org</url>
 
   <url type="homepage">https://www.kde.org</url>
   <url type="bugtracker">https://bugs.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</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>
 
   <screenshots>
 
     <screenshot type="default">
 
     <screenshot type="default">
 
       <image>
 
       <image>
         https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-screenshots
+
         see https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-screenshots
         Central hosting is still being sorted out, poke [email protected]kde.org for more info.
+
         Central hosting for uploading at https://phabricator.kde.org/source/websites-product-screenshots/
 +
        Central URL to use here https://cdn.kde.org/screenshots/...
 
       </image>
 
       </image>
 
     </screenshot>
 
     </screenshot>
 
   </screenshots>
 
   </screenshots>
 
   <provides>
 
   <provides>
     <binary>$YOURBINARYNAME!</binary>
+
     <binary>$YOURBINARYNAME</binary>
 
   </provides>
 
   </provides>
 
   <project_group>KDE</project_group>
 
   <project_group>KDE</project_group>
 
</component>
 
</component>
 
</syntaxhighlight>}}
 
</syntaxhighlight>}}
 +
 +
== 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 [https://kde.org/applications 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/ 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 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 [https://forum.kde.org/ 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).

Latest revision as of 16:32, 4 October 2019

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

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


This page was last edited on 4 October 2019, at 16:32. Content is available under Creative Commons License SA 4.0 unless otherwise noted.