MetaInfo/DesktopApps: Difference between revisions

Revision as of 17:29, 17 June 2016

Under Construction
This is a new page, currently under construction!

Introduction

Every software center that exists allows the user to look at screenshots and a long description of the application before it is installed. For most users it allows them to answer the question Do I want to install this application?

Traditionally in Linux distributions, we have none of this data for the vast majority of our desktop user-installable applications. To solve this, the AppStream project provides a metadata XML specification for projects to specify this data. For applications, these files are also called "AppData" files.

Applications wishing to have long descriptions, screenshots and other useful things are required to ship one or more files in /usr/share/metainfo/%{id}.appdata.xml.

File Specification

Sample File

The file should contain something like this:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Copyright 2014 First Lastname <[email protected]> -->
<component type="desktop">
  <id>ark.desktop</id>
  <metadata_license>FSFAP</metadata_license>
  <project_license>GPL-2.0+</project_license>
  <name>Ark</name>
  <summary>Archiving Tool</summary>
  <description>
    <p>
      Ark is a graphical file compression/decompression utility with support for multiple formats,
      including tar, gzip, bzip2, rar and zip, as well as CD-ROM images.
      Ark can be used to browse, extract, create, and modify archives. 
    </p>
    <p>Features:</p>
    <ul>
      <li>Several forums supported: gzip, bzip2, zip, rar, 7z and more</li>
      <li>Preview file contents without extracting files</li>
    </ul>
    <p>
      Additional information on why the user wants this application....
    </p>
  </description>
  <screenshots>
    <screenshot type="default">
      <image width="834" height="651">http://kde.org/images/screenshots/ark.png</image>
    </screenshot>
    <screenshot>
      <image width="800" height="600">http://kde.org/images/screenshots/ark-feature2.png</image>
    </screenshot>
  </screenshots>
  <url type="homepage">http://kde.org/applications/utilities/ark/</url>
  <url type="bugtracker">https://bugs.kde.org/enter_bug.cgi?format=guided&amp;product=ark</url>
  <project_group>KDE</project_group>
  <provides>
    <binary>ark</binary>
  </provides>
</component>

Component type

The type property of the <component/> root node must be set to desktop in order for the application to show up in software-centers.

<id/>

The %{id} is the same name as the installed .desktop file for the application.

<metadata_license/>

The <metadata_license> tag is indicating the content licence that you are releasing the one AppData XML file as. This is not typically the same as the project licence. By ommitting the licence value would probably mean your data would not be incorporated into the distribution metadata. Permissible licence codes include:

CC0-1.0
CC-BY-3.0
CC-BY-SA-3.0
GFDL-1.3
MIT

The licence codes correspond to the full licence texts as given by the SPDX OpenSource License Registry. It is a good idea to choose a permissive license for your metadata, so distributions can easily bundle it with metadata from other projects. For more information, see the definition of the <project_license/> tag in the AppStream docs.

<project_license/>

The license your project is licensed under. This tag is the same as the tag defined in the AppStream docs, and the same rules for license names apply.

<name/>

You can omit this tag if you want the software center to have the same strings as the desktop menu. In some cases it might be required to have a different name in the software-center, but most appdata.xml files will not need to explicitly define this.

<summary/>

You can omit this tag if you want the software center to have the same strings as the desktop menu. In some cases it might be required to have a different name in the software-center, but most appdata.xml files will not need to explicitly define this.

<description/>

The long description is an important part of the file. Important things to consider when writing the application description:

Include 2-3 paragraphs of interesting easy to read prose.
Ensure you provide a description of what the application actually does.
Describe any important features.
Do not use possily trademarked product names when refering to competitors.
Break down each paragraph into easily translated paragraphs.
Use lists sparingly.
Never refer to installable items as packages.
Never start the first sentance with This application...
Try not use more than 100 words.
Do not be too geeky. Aim for an intelligent semi-technical reader.
Don't mention what language an application is written in, users don't care
Only mention what the application can do now, rather than what is planned

Do not assume the format is HTML. Only paragraph, ordered list and unordered list are supported at this time.

<screenshots/>

A screenshot presents your application to the outside world, and could be seen by hundreds or thousands of people.

Screenshots are an important part of how people choose which applications to install, so it's important to get them right. Consistent, good looking screenshots will make your application look more attractive and will expand your userbase. Consistent screenshots also provide a more predictable experience for people using the software center.

Screenshot size, shape and format:

All screenshots should have a 16:9 aspect ratio, and should have a width that is no smaller than 620px (this will ensure that your screenshots correctly fit into the space provided by the software-center). Ideally the window will be resized to a 16:9 aspect ratio, but screenshots can also be cropped if only a small area of the window needs to be shown.
Screenshots should be in PNG or JPEG format. PNG is the preferred format; JPEG should only be used when screenshots include large photographs or other images where a lossy format JPEG format may compress better.
Do not scale screenshots below their original size.

Basic guidelines for things to include (and not include) in your screenshots:

Use the default visual and theme settings, including the default font, icons, and window controls. Avoid including your own tweaks to the KDE standard design.
Screenshots should be taken with US English as the display language.
Your default screenshot should give an overview of your application, and should show an entire application window. It can be combined with screenshots which show specific aspects of the application.
Screenshots should not show anything outside the application's windows (including the background wallpaper). If you are taking a screenshot of the whole window, you can for example use the "Window Under Cursor" mode of KSnapshot (including any window borders in the screenshot, and ensuring that the resulting image has an alpha mask for the rounded corners).
Some applications, such as games, primarily run full screen. Screenshots of these applications should be taken with the application running full screen - there should be no visible window controls in the screenshot.
Don't add shadows to your screenshots.
Do not include content that might be considered offensive or controversial, and avoid showing personal information. Remember that your screenshots will be visible to the internet at large.

Additional advice on how to take effective screenshots:

Each of your screenshots should focus on one thing and one thing only. Screenshot one window at a time, and avoid having overlapping windows or user interface elements. This will make it much easier of people to understand what you are showing them.
If a screenshot is demonstrating a single feature or aspect of the application, crop it to exclude irrelevant detail.
Screenshots often need to feature content, such as images, documents, web pages or videos. Don’t show your application in an ‘empty’ state, and try and use high quality content which has positive associations and broad appeal.
In general, you shouldn't include the mouse pointer in your screenshots.

See the section on screenshots in the AppStream documentation for more information.

<url/>

Links of type homepage should be a link to the upstream homepage for the application. The type bugtracker should be a link to the project's bugtracker, ideally an URL for the "Report New Bug" formular. Links of type faq should point to a website displaying a summary of frequently asked questions about the application. You may also want to consider to add a link of type donation, pointing at a page with information how to donate to your project.

<project_group/>

If you include the <project_group> tag then this identifies your project with a specific upstream umbrella project. Known values include GNOME, KDE, XFCE, Apache and Mozilla. "Umbrella project" means that you use all infrastructure and policies, for instance string freezes dates, bugtracker and source control instance, of the umbrella project. KDE projects should obviously set their project-group to "KDE".

<provides/>

The <provides> tag allows you to specify the public interfaces your project provides. In case of an application, this is usually a binary installed into a directory in PATH. Distributors must ensure that the package which contains the metadata file contains or at least depends on the items specified in the <provides> tag, Projects may install multiple metadata files specifying different components, to make it easier for distributors to split up the project's binaries into different packages.

Other

There are some other tags you can use to describe your application. A full list is available at the documentation of generic components and desktop applications in the AppStream documentation.

Questions

See also the more general questions at the main page on metadata.

What resolution screenshots should I aim to take?

Any 16:9 aspect resolution is fine, as long as the width is at least 624 pixels. A useful table of resolutions of the correct aspect can be found here:

640x360	800x450	960x540	1120x630	1280x720	1440x810
656x369	816x459	976x549	1136x639	1296x729	1456x819
672x378	832x468	992x558	1152x648	1312x738	1472x828
688x387	848x477	1008x567	1168x657	1328x747	1488x837
704x396	864x486	1024x576	1184x666	1344x756	1504x846
720x405	880x495	1040x585	1200x675	1360x765	1520x855
736x414	896x504	1056x594	1216x684	1376x774	1536x864
752x423	912x513	1072x603	1232x693	1392x783	1552x873
768x432	928x522	1088x612	1248x702	1408x792	1568x882
784x441	944x531	1104x621	1264x711	1424x801	1584x891

The native size for most software centers is 624x351 and so screenshots taken or cropped to this size will not be resized and will look pixel perfect. The largest resolution screenshot supported is 1600x900.

Do you have some example patches on added AppData?

Yes. Take a look at this patch against Trojita to see how a simple Appdata file was added. For a more complex example, where application and library metadata was added, take a look at this patch against KGraphViewer.