GNOME Goal: AppData files for GNOME-Software

gnome-software-screenshot.png

Guidelines

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, we have defined a new data file, which the upstream project can optionally translate using the same technique as GSetting schemas or Desktop files. Rather than create a new schema from scratch, we'll be using a subset of the AppStream metadata proposal.

Applications wishing to have long descriptions, screenshots and other useful things are required to ship one or more files in /usr/share/appdata/%{id}.appdata.xml. In GNOME 3.14, we will only be showing applications that include AppData information, but until then it's optional but highly recommended.

{i} Instructions on how to recognize a module affected by this goal.

A module is affected by this goal if it ships a <app_id>.desktop file but doesn't ship a <app_id>.appdata.xml.in file. You can get more information about AppData file and how to create and distribute them at Richard Hughes' blog and the Official specification document. The specification document provides a lot of detail on the style of the description and describes all the tags in detail. You probably want to read it before starting to write an AppData file for a project.

If your desktop file is hidden, e.g. NoDisplay=true or if it does not have Type=Application, you do not need to create an AppData file as it will not show in the software center.

To apply this goal to an application, you should create a xml.in file with the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<component type="desktop">
 <id>gnome-power-statistics.desktop</id>
 <!-- this is the licence of the appdata file, not the project. As specified in the SPDX OpenSource License Registry -->
 <licence>CC0-1.0</licence>
 <!-- Only include 'name' if you want the software center name to be different to the 'Name' in the .desktop file -->
 <name>Power Statistics</name>
 <!-- Only include 'summary' if you want the software center name to be different to the 'Comment' in the .desktop file -->
 <summary>Observe power management</summary>
 <description>
  <p>
   Power Statistics is a program used to view historical and current battery
   information and will show programs running on your computer using power.
  </p>
  <p>Example list:</p>
  <!-- try not to use lists unless you have to. Paragraphs look a lot better in nearly all cases -->
  <ul>
   <li>First item</li>
   <li>Second item</li>
  </ul>
  <p>
  You probably only need to install this application if you are having problems
  with your laptop battery, or are trying to work out what programs are using
  significant amounts of power.
  </p>
 </description>
 <screenshots>
  <screenshot type="default">
   <image>http://www.hughsie.com/en_US/main.png</image>
  </screenshot>
  <screenshot>
   <image>http://www.hughsie.com/en_US/preferences.png</image>
  </screenshot>
 </screenshots>
 <url type="homepage">http://www.gnome.org/projects/en_US/gnome-power-manager</url>
 <!-- this is someone that wants to be notified when we add to the appdata specification -->
 <update_contact>gnome-power-manager-list@gnome.org</update_contact>
</component>

If you want to mark a string for translation, use something like this (full patch):

  <_p>
   Power Statistics is a program used to view historical and current battery
   information and will show programs running on your computer using power.
  </_p>
  <ul>
   <_li>First item</_li>
   <_li>Second item</_li>
  </ul>

A couple of common translation mistakes to avoid:

  • You need to distribute the .appdata.xml.in file, NOT the generated .appdata.xml, or out of tree builds will fail. dist_appdata_DATA in a Makefile.am is a mistake.

  • You want to use @INTLTOOL_XML_RULE@ to merge the translations into the generated .appdata.xml file. @INTLTOOL_XML_NOMERGE_RULE@ cannot be used and is no longer necessary for gsettings translations.

You should validate your .appdata.xml (after being generated from the .appdata.xml.in file) AppData file using the appstream-util validate tool available in appstream-glib. Files should validate with no warnings or errors. It is up to the maintainer if they want to validate the file in the build system, but if so, ensure to check for /usr/bin/appstream-util in the configure script also.

You should install the <id>.appdata.xml file to /usr/share/appdata/. This is to allow the software center to work in a limited way when the downstream distribution does not generate AppStream metadata from the AppData files.

Some applications we wanted to feature in 3.10 have already had AppData files written, and these are stored in a temporary location. If you copy a file from this repository ensure it's validated and translated before committing upstream. When the upstream project does a tarball release with the new AppData file the corresponding file will be automatically deleted in fedora-appstream if it exists. The files in fedora-appstream will also be cleared before 3.12, as the files are supposed to live, and be translated, upstream.

Comments before approval

{i} Add your comments to this goal proposal here

Status of this goal

{i} Tip: If you choose to work on a module, create the bug report on the GNOME bugzilla for the relevant module, and make it block bug <<insert here a link to the tracker bug>>. This way people will know someone already works on it, and won't duplicate the work you're doing.

Patch Status

Markup

todo

<: #ff8080> todo

patch

<: #ffcc50> [[GnomeBug:xxxxx|patch]]

done

<: #80ff80> [[GnomeBug:xxxxx|done]]

not needed

<: #80ff80> not needed

Above are the states and corresponding markup to update the modules state table below.

Tarball

Status

core

at-spi2-core

not needed

at-spi2-atk

not needed

dconf

done

evolution-data-server

not needed

glib-networking

not needed

gnome-bluetooth

done

gnome-online-accounts

not needed

gnome-control-center

not needed

gnome-desktop

not needed

gnome-icon-theme

not needed

gnome-icon-theme-extras

not needed

gnome-icon-theme-symbolic

not needed

gnome-keyring

to do

gnome-menus

not needed

gnome-packagekit

done

gnome-power-manager

done

gnome-screensaver

obsolete

gnome-session

not needed

gnome-settings-daemon

not needed

gnome-shell

not needed

gnome-themes-standard

not needed

gsettings-desktop-schemas

not needed

gvfs

not needed

mousetweaks

to do

mutter

not needed

network-manager-applet

to do

pulseaudio

to do

telepathy-mission-control

to do

core-utilities

baobab

done, but fails to validate

brasero

done

empathy

done

eog

done

epiphany

done, but fails to validate

evince

patch

gnome-calculator

done

gnome-contacts

done

gnome-dictionary

done

gnome-disk-utility

done

gnome-font-viewer

done

gnome-screenshot

done

gnome-search-tool

to do

gnome-system-log

to do

gnome-system-monitor

done

gnome-terminal

to do sample here

gucharmap

done

nautilus

done

sushi

to do

yelp

patch

core-extras

gnome-backgrounds

not needed

gnome-user-share

not needed

vino

not neededo

gnome-user-docs

to do

core-fallback

gconf-editor

done

gnome-panel

not needed

metacity

not needed

notification-daemon

not needed

core-os-services

accountservice

not needed

avahi

not needed

ConsoleKit

not needed

dbus

not needed

gdm

to do

NetworkManager

not needed

PackageKit

not needed

polkit

not needed

upower

not needed

core-deps

atk

not needed

atkmm

not needed

cairo

not needed

cairomm

not needed

cantarell-fonts

not needed

caribou

to do

clutter

not needed

clutter-gtk

not needed

clutter-gst

not needed

cogl

not needed

dbus-glib

not needed

dbus-python

not needed

desktop-file-utils

not needed

enchant

not needed

expat

not needed

farsight2

not needed

folks

not needed

fontconfig

not needed

gamin

not needed

gnome-js-common

not needed

gtksourceview

not needed

gdk-pixbuf

not needed

gjs

not needed

glib

not needed

glibmm

not needed

gmime

not needed

gnome-doc-utils

not needed

gnome-video-effects

not needed

gnutls

not needed

gobject-introspection

not needed

gst-plugins-base

not needed

gst-plugins-good

not needed

gst-plugins-farsight

not needed

gstreamer

not needed

gtk+

not needed

gtk-doc

not needed

gtkmm

not needed

gudev

not needed

hicolor-icon-theme

not needed

icon-naming-utils

not needed

iso-codes

not needed

itstool

not needed

intltool

not needed

java-gnome

not needed

js185

not needed

json-glib

not needed

libatasmart

not needed

libcanberra

not needed

libchamplain

not needed

libcroco

not needed

libdaemon

not needed

libdiscid

not needed

libgpg-error

not needed

libgcrypt

not needed

libgee

not needed

libgdata

not needed

libgnome-keyring

not needed

libgnomekbd

not needed

libgsf

not needed

libgtop

not needed

libgweather

not needed

libical

not needed

libmusicbrainz

not needed

libnice

not needed

libnotify

not needed

liboauth

not needed

libpeas

not needed

libproxy

not needed

librest

not needed

librsvg

not needed

libsigc++2

not needed

libsndfile

not needed

libsoup

not needed

libtasn1

not needed

libwnck

not needed

libxklavier

not needed

libxml2

not needed

libxslt

not needed

mm-common

not needed

nspr

not needed

nss

not needed

p11-kit

not needed

pango

not needed

pangomm

not needed

pixman

not needed

polkit-gnome

not needed

poppler

not needed

py2cairo

not needed

pygobject

not needed

rarian

not needed

seed

not needed

shared-mime-info

not needed

sound-theme-freedesktop

not needed

speex

not needed

sqlite3

not needed

startup-notification

not needed

telepathy-glib

not needed

telepathy-logger

not needed

telepathy-farsight

not needed

totem-pl-parser

not needed

tracker

to do

vala

not needed

vte

to do

webkit

not needed

yelp-tools

to do

yelp-xsl

not needed

zenity

not needed

libnl

not needed

lcms2

not needed

colord

not needed

apps

accerciser

to do

aislerot

to do

anjuta

done

banshee

done (master and stable-2.6 branches, upcoming 2.9.0 and 2.6.2 respectively)

bijiben

done

cheese

done

d-feet

done

devhelp

done

evolution

done

file-roller

to do

five-or-more

done

four-in-a-row

done

frogr

done

gedit

done

ghex

to do sample here

glade

done

gnome-chess

done

gnome-clocks

(done)

gnome-color-manager

done

gnome-devel-docs

to do

gnome-documents

done, but fails to validate

gnome-klotski

done

gnome-mahjongg

done

gnome-maps

done, but fails to validate

gnome-mines

done

gnome-nettool

to do

gnome-nibbles

done

gnome-photos

done

gnome-robots

done

gnome-sudoku

done

gnome-tetravex

done

gnome-tweak-tool

done

gnome-weather

done, but fails to validate

gtranslator

done

iagno

done

lightsoff

done

nautilus-sendto

to do

nemiver

done

orca

to do

quadrapassel

done

rygel

to do

seahorse

done

swell-foop

done

tali

done

totem

done

vinagre

done

Initiatives/GnomeGoals/AppDataGnomeSoftware (last edited 2015-12-22 15:28:21 by CorentinNoël)