MetaInfo/DesktopApps: Difference between revisions

    From KDE TechBase
    No edit summary
    No edit summary
     
    Line 99: Line 99:


    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.
    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.
    Central screenshot hosting is provided via the git repo https://phabricator.kde.org/source/websites-product-screenshots/ (note the readme)


    Screenshot size, shape and format:
    Screenshot size, shape and format:

    Latest revision as of 08:46, 29 November 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-application">
      <id>org.kde.ark</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 (the .desktop suffix can be omitted with newer (>> 2016) versions of AppStream).

    <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:

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

    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.

    Central screenshot hosting is provided via the git repo https://phabricator.kde.org/source/websites-product-screenshots/ (note the readme)

    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.

    Further Reading

    The AppStream documentation also contains information about the meta-info files shipped in upstream projects. Our friends at GNOME also have their own version of a short application-metadata howto, where the instructions on this page are derived from. You can check it out here.